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

# Transaction Model

> The transaction data model represents purchase records in the Cobi system, including savings and discount information.

<Note>
  **Important**: The transaction 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 transactions.
</Note>

## Schema

```json theme={null}
{
  "type": "object",
  "required": ["transaction_id", "shop_id", "region", "savings", "amount"],
  "properties": {
    "transaction_id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier for the transaction"
    },
    "student_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "ID of the student making the purchase"
    },
    "shop_id": {
      "type": "string",
      "format": "uuid",
      "description": "ID of the shop where the transaction occurred (must reference an existing shop)"
    },
    "offer_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "ID of the offer used"
    },
    "branch_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true,
      "description": "ID of the branch location"
    },
    "region": {
      "type": "string",
      "description": "Geographic region of the transaction (2-letter country code, ISO 3166-1 alpha-2)"
    },
    "source": {
      "type": "string",
      "nullable": true,
      "description": "Source of the transaction (e.g., 'online', 'in-store')"
    },
    "savings": {
      "type": "number",
      "format": "float",
      "description": "Amount saved in the transaction (must be a non-negative number)"
    },
    "amount": {
      "type": "number",
      "format": "float",
      "description": "Total transaction amount (must be a positive number)"
    },
    "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"
    },
    "discount_name": {
      "type": "string",
      "nullable": true,
      "description": "Name of the discount applied"
    },
    "discount_type": {
      "type": "string",
      "nullable": true,
      "description": "Type of discount (e.g., 'percentage', 'fixed')"
    },
    "discount_value": {
      "type": "number",
      "format": "float",
      "nullable": true,
      "description": "Value of the discount"
    }
  }
}
```

## Field Descriptions

### Required Fields

| Field            | Type   | Format | Description                                                                  |
| ---------------- | ------ | ------ | ---------------------------------------------------------------------------- |
| `transaction_id` | string | UUID   | Unique identifier for the transaction                                        |
| `shop_id`        | string | UUID   | ID of the shop where the transaction occurred (must reference existing shop) |
| `region`         | string | -      | Geographic region (2-letter country code, e.g., "CA" for Canada)             |
| `savings`        | number | float  | Amount saved in the transaction (must be a non-negative number)              |
| `amount`         | number | float  | Total transaction amount (must be a positive number)                         |

### Optional Fields

| Field            | Type    | Format    | Description                                            |
| ---------------- | ------- | --------- | ------------------------------------------------------ |
| `student_id`     | string  | UUID      | ID of the student making the purchase                  |
| `offer_id`       | string  | UUID      | ID of the offer used                                   |
| `branch_id`      | string  | UUID      | ID of the branch location                              |
| `source`         | string  | -         | Source of the transaction (e.g., "online", "in-store") |
| `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     |
| `discount_name`  | string  | -         | Name of the discount applied                           |
| `discount_type`  | string  | -         | Type of discount (e.g., "percentage", "fixed")         |
| `discount_value` | number  | float     | Value of the discount                                  |

## Example

```json theme={null}
{
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "student_id": "550e8400-e29b-41d4-a716-446655440001",
  "shop_id": "550e8400-e29b-41d4-a716-446655440002",
  "offer_id": "550e8400-e29b-41d4-a716-446655440003",
  "branch_id": "550e8400-e29b-41d4-a716-446655440004",
  "region": "CA",
  "source": "online",
  "savings": 10.5,
  "amount": 100.0,
  "created": "2023-01-15T14:30:00Z",
  "updated": "2023-06-22T09:15:30Z",
  "is_deleted": false,
  "discount_name": "Student Discount",
  "discount_type": "percentage",
  "discount_value": 10
}
```

## Best Practices

1. **UUID Format**: Use valid UUID v4 format for all ID fields
2. **Numeric Values**: Use decimal numbers for monetary values
3. **Region Codes**: Use ISO 3166-1 alpha-2 country codes (e.g., "CA" for Canada, "US" for United States)
4. **Data Consistency**: Ensure consistent data across all transaction records
5. **Discount Information**: Provide complete discount details when available
6. **Data Dependencies**: Ensure shop\_id references an existing shop

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