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

# Branch Model

> The category data model represents information about shop categories in the Cobi system.

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

## Schema

```json theme={null}
{
  "type": "object",
  "required": ["branch_id", "shop_id", "name", "region"],
  "properties": {
    "branch_id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier for the branch"
    },
    "shop_id": {
      "type": "string",
      "format": "uuid",
      "description": "ID of the shop this branch belongs to (must reference an existing shop)"
    },
    "name": {
      "type": "string",
      "description": "Name of the branch"
    },
    "region": {
      "type": "string",
      "description": "Geographic region (2-letter country code, ISO 3166-1 alpha-2)"
    },
    "latitude": {
      "type": "number",
      "nullable": true,
      "description": "Latitude coordinate of the branch location"
    },
    "longitude": {
      "type": "number",
      "nullable": true,
      "description": "Longitude coordinate of the branch location"
    },
    "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"
    }
  }
}
```

## Field Descriptions

### Required Fields

| Field       | Type   | Format | Description                                                         |
| ----------- | ------ | ------ | ------------------------------------------------------------------- |
| `branch_id` | string | UUID   | Unique identifier for the branch                                    |
| `shop_id`   | string | UUID   | ID of the shop this branch belongs to (must reference a valid shop) |
| `name`      | string | -      | Name of the branch                                                  |
| `region`    | string | -      | Geographic region (2-letter country code, e.g., "CA" for Canada)    |

### Optional Fields

| Field        | Type    | Format    | Description                                        |
| ------------ | ------- | --------- | -------------------------------------------------- |
| `latitude`   | number  | -         | Latitude coordinate of the branch location         |
| `longitude`  | number  | -         | Longitude coordinate of the branch location        |
| `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 |

## Example

```json theme={null}
{
  "branch_id": "550e8400-e29b-41d4-a716-446655440000",
  "shop_id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "Downtown Branch",
  "region": "CA",
  "latitude": 43.65107,
  "longitude": -79.347015,
  "created": "2023-01-15T14:30:00Z",
  "updated": "2023-06-22T09:15:30Z",
  "is_deleted": false
}
```

## Best Practices

1. **UUID Format**: Use valid UUID v4 format for branch\_id and shop\_id
2. **Data Dependencies**: Ensure shop\_id references an existing shop
3. **Region Codes**: Use ISO 3166-1 alpha-2 country codes (e.g., "CA" for Canada, "US" for United States)
4. **Coordinates**: When providing latitude and longitude, ensure they are valid geographic coordinates
5. **Data Consistency**: Ensure consistent data across all branch records

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