> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hellocobi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Offers

> Upload offer records to the Cobi Data API

<Note>
  **Important**: Offer records have a dependency on shops. The system validates
  the `shop_id` field against existing records in the database. You should
  upload shops before uploading offers to ensure proper data validation.
</Note>

## Authentication Required

This endpoint requires API key authentication via Bearer token in the Authorization header.

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## About the Data API

This endpoint is part of the Cobi Data API (`/v1/data/:type`), which provides a consistent interface for uploading different types of structured data.

## Request Body

<ParamField body="records" type="array" required>
  An array of offer records (up to 5000)

  <Expandable title="Offer Record">
    <ParamField body="offer_id" type="string (UUID)" required>
      Unique identifier for the offer
    </ParamField>

    <ParamField body="shop_id" type="string (UUID)" required>
      ID of the shop offering the discount (must reference an existing shop)
    </ParamField>

    <ParamField body="name" type="string" required>
      Name of the offer
    </ParamField>

    <ParamField body="type" type="string" required>
      Type of offer (e.g., "percentage", "fixed")
    </ParamField>

    <ParamField body="value" type="number (float)" required>
      Value of the offer (must be a positive number)
    </ParamField>

    <ParamField body="region" type="string" required>
      Geographic region (2-letter country code, e.g., "CA" for Canada)
    </ParamField>

    <ParamField body="allowed_from" type="string (date-time)">
      Start date and time of the offer
    </ParamField>

    <ParamField body="allowed_to" type="string (date-time)">
      End date and time of the offer
    </ParamField>

    <ParamField body="allowed_branches" type="string">
      Comma-separated list of branch IDs where the offer is valid
    </ParamField>

    <ParamField body="allowed_days" type="string">
      Comma-separated list of days when the offer is valid
    </ParamField>

    <ParamField body="created" type="string (date-time)">
      Timestamp when the record was created
    </ParamField>

    <ParamField body="updated" type="string (date-time)">
      Timestamp when the record was last updated
    </ParamField>

    <ParamField body="is_deleted" type="boolean">
      Flag indicating if the record is marked as deleted
    </ParamField>

    <ParamField body="is_enabled" type="boolean">
      Flag indicating if the offer is currently enabled
    </ParamField>
  </Expandable>
</ParamField>

## Response

The API returns a JSON response with the following fields:

```json theme={null}
{
  "request_id": "string", // Unique ID for the overall request
  "type": "offers", // Type of data being processed
  "batches": [
    {
      "batch": 1, // Sequential batch number
      "status": 200, // HTTP-like status code (200, 207, 400, 500)
      "data": {
        "status": "success", // "success", "partial", or "error"
        "type": "offers", // Matches the top-level type
        "message": "Records uploaded successfully", // Summary message
        "request_id": "string",
        "batch_id": "string",
        "error": "" // Optional — empty or null on success; contains error details otherwise
      }
    }
  ]
}
```

| Field                       | Type   | Description                                   |
| --------------------------- | ------ | --------------------------------------------- |
| `request_id`                | string | Unique ID for the overall request             |
| `type`                      | string | Type of data being processed (e.g., "offers") |
| `batches`                   | array  | Array of batch results                        |
| `batches[].batch`           | int    | Sequential batch number                       |
| `batches[].status`          | int    | HTTP-like status code (200, 207, 400, 500)    |
| `batches[].data`            | object | Batch result details                          |
| `batches[].data.status`     | string | "success", "partial", or "error"              |
| `batches[].data.type`       | string | Matches the top-level type                    |
| `batches[].data.message`    | string | Summary message of the batch result           |
| `batches[].data.request_id` | string | Unique request ID for the batch               |
| `batches[].data.batch_id`   | string | Unique batch ID                               |
| `batches[].data.error`      | string | Error details (empty or null on success)      |

## Error Codes

| Status Code | Description                               | data.status value |
| ----------- | ----------------------------------------- | ----------------- |
| 200         | All records processed successfully        | success           |
| 207         | Some records failed, others succeeded     | partial           |
| 400         | Validation or dependency error            | error             |
| 500         | Internal or unexpected server error       | error             |
| 401         | Unauthorized - Invalid or missing API key | error             |

## Example

```bash theme={null}
curl -X POST https://api.hellocobi.com/v1/data/offers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "offer_id": "550e8400-e29b-41d4-a716-446655440000",
        "shop_id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "Student Discount",
        "type": "percentage",
        "value": 10.0,
        "region": "CA",
        "allowed_from": "2024-01-01T00:00:00Z",
        "allowed_to": "2024-12-31T23:59:59Z",
        "allowed_branches": "branch1,branch2",
        "allowed_days": "monday,tuesday,wednesday",
        "is_enabled": true
      }
    ]
  }'
```

## Best Practices

1. **Upload Order**: Upload shops before offers to ensure references exist
2. **Batch Size**: Upload up to 5000 records at a time for optimal performance
3. **Data Validation**: Ensure all required fields are present and properly formatted
4. **Error Handling**: Implement proper error handling for failed requests
5. **Rate Limiting**: Be mindful of API rate limits

Need help? Contact our support team at [support@hellocobi.com](mailto:support@hellocobi.com)