> ## 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.

# Offer Model

> The offer data model represents discounts and promotions in the Cobi system.

<Note>
  **Important**: The offer model has a dependency on the shop model. The
  `shop_id` field must reference an existing shop. It's recommended to upload
  shop data before uploading offers.
</Note>

## Schema

```json theme={null}
{
  "type": "object",
  "required": ["offer_id", "shop_id", "name", "type", "value", "region"],
  "properties": {
    "offer_id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier for the offer"
    },
    "shop_id": {
      "type": "string",
      "format": "uuid",
      "description": "ID of the shop offering the discount (must reference an existing shop)"
    },
    "name": {
      "type": "string",
      "description": "Name of the offer"
    },
    "type": {
      "type": "string",
      "description": "Type of offer (e.g., 'percentage', 'fixed')"
    },
    "value": {
      "type": "number",
      "format": "float",
      "description": "Value of the offer (must be a positive number)"
    },
    "region": {
      "type": "string",
      "description": "Geographic region where the offer is valid (2-letter country code, ISO 3166-1 alpha-2)"
    },
    "allowed_from": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "Start date and time of the offer"
    },
    "allowed_to": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "End date and time of the offer"
    },
    "allowed_branches": {
      "type": "string",
      "nullable": true,
      "description": "Comma-separated list of branch IDs where the offer is valid"
    },
    "allowed_days": {
      "type": "string",
      "nullable": true,
      "description": "Comma-separated list of days when the offer is valid"
    },
    "created": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "Timestamp when the record was created"
    },
    "updated": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "Timestamp when the record was last updated"
    },
    "is_deleted": {
      "type": "boolean",
      "nullable": true,
      "description": "Flag indicating if the record is marked as deleted"
    },
    "is_enabled": {
      "type": "boolean",
      "nullable": true,
      "description": "Flag indicating if the offer is currently enabled"
    }
  }
}
```

## Field Descriptions

### Required Fields

| Field      | Type   | Format | Description                                                         |
| ---------- | ------ | ------ | ------------------------------------------------------------------- |
| `offer_id` | string | UUID   | Unique identifier for the offer                                     |
| `shop_id`  | string | UUID   | ID of the shop offering the discount (must reference existing shop) |
| `name`     | string | -      | Name of the offer                                                   |
| `type`     | string | -      | Type of offer (e.g., "percentage", "fixed")                         |
| `value`    | number | float  | Value of the offer (must be a positive number)                      |
| `region`   | string | -      | Geographic region (2-letter country code, e.g., "CA" for Canada)    |

### Optional Fields

| Field              | Type    | Format    | Description                                           |
| ------------------ | ------- | --------- | ----------------------------------------------------- |
| `allowed_from`     | string  | date-time | Start date and time of the offer (ISO 8601)           |
| `allowed_to`       | string  | date-time | End date and time of the offer (ISO 8601)             |
| `allowed_branches` | string  | -         | Comma-separated list of branch IDs                    |
| `allowed_days`     | string  | -         | Comma-separated list of days (e.g., "monday,tuesday") |
| `created`          | string  | date-time | Timestamp when the record was created                 |
| `updated`          | string  | date-time | Timestamp when the record was last updated            |
| `is_deleted`       | boolean | -         | Flag indicating if the record is marked as deleted    |
| `is_enabled`       | boolean | -         | Flag indicating if the offer is currently enabled     |

## Example

```json theme={null}
{
  "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",
  "created": "2023-01-15T14:30:00Z",
  "updated": "2023-06-22T09:15:30Z",
  "is_deleted": false,
  "is_enabled": true
}
```

## Best Practices

1. **UUID Format**: Use valid UUID v4 format for all ID fields
2. **Date/Time Format**: Use ISO 8601 format for date-time fields
3. **Region Codes**: Use ISO 3166-1 alpha-2 country codes (e.g., "CA" for Canada, "US" for United States)
4. **Offer Types**: Use consistent offer types across your system (e.g., "percentage", "fixed")
5. **Value Format**: Use decimal numbers for monetary values
6. **List Format**: Use comma-separated values for allowed\_branches and allowed\_days
7. **Data Dependencies**: Ensure shop\_id references an existing shop

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