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

# Common objects

> Shared data structures that appear across multiple Clopos Open API v2 endpoints

# Common objects

Several data structures are reused across v2 endpoints. This page defines them once so individual endpoint pages can reference rather than repeat them.

## Response envelope

Every successful v2 response wraps the result in a consistent envelope:

```json theme={null}
{
  "success": true,
  "data": [ ... ],
  "total": 196,
  "time": 138,
  "timestamp": "2026-01-19 14:51:33",
  "unix": 1768820869,
  "sorts": ["id", "created_at", "updated_at", ...]
}
```

| Field       | Type            | Description                                                                                                                                             |
| ----------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `success`   | boolean         | `true` on success. Always check this first — one edge case (`test/production mismatch`) returns HTTP `200` with `success: false`.                       |
| `data`      | object or array | The requested resource(s). An **object** for single-resource endpoints (`GET /v2/receipts/1`), an **array** for list endpoints (`GET /v2/receipts`).    |
| `total`     | integer         | *(List endpoints only.)* Total number of records matching the query, before pagination. Use this alongside `page` and `limit` to calculate total pages. |
| `time`      | integer         | Server-side response time in milliseconds. Useful for monitoring but not guaranteed to be stable — do not use for business logic.                       |
| `timestamp` | string          | Server timestamp in `YYYY-MM-DD HH:mm:ss` format (UTC).                                                                                                 |
| `unix`      | integer         | Same timestamp as a Unix epoch in seconds.                                                                                                              |
| `sorts`     | array           | *(List endpoints only.)* The field names accepted by `sort[0]`. Query the list once to discover which fields are sortable for a given resource.         |

### Pagination

List endpoints accept these query parameters:

| Parameter | Type    | Default      | Description                                                   |
| --------- | ------- | ------------ | ------------------------------------------------------------- |
| `page`    | integer | `1`          | Page number (1-based).                                        |
| `limit`   | integer | `50`         | Records per page. Maximum varies by resource (typically 200). |
| `sort[0]` | string  | `created_at` | Field to sort by (must be a value from `sorts`).              |
| `sort[1]` | integer | `-1`         | Sort direction: `1` = ascending, `-1` = descending.           |

### Filtering

Many list endpoints support date-range and field-level filters:

| Parameter       | Type   | Description                           |
| --------------- | ------ | ------------------------------------- |
| `date[0]`       | string | Start date (inclusive), `YYYY-MM-DD`. |
| `date[1]`       | string | End date (inclusive), `YYYY-MM-DD`.   |
| `filters[N][0]` | string | Field name to filter on.              |
| `filters[N][1]` | string | Value to match.                       |

```bash theme={null}
# Receipts created between Jan 1-31, with status = 2 (closed)
?date[0]=2026-01-01&date[1]=2026-01-31&filters[0][0]=status&filters[0][1]=2
```

### Error envelope

Failed requests use the same top-level shape but with `success: false`. See [Errors](/errors) for the full reference.

***

## Media

The `media` field appears on categories, products, venues, sale types, users, and payment methods. It is an array of media objects — typically images uploaded through the Clopos dashboard.

```json theme={null}
"media": [
  {
    "uuid": "1d76f22b-c209-4fac-be3a-cfde7b8f0d74",
    "mime_type": "image/jpeg",
    "size": 87281,
    "urls": {
      "original": "https://cdn.clopos.com/omega/1d76f22b-.../original.jpg",
      "extra_large": "https://cdn.clopos.com/omega/1d76f22b-.../extra_large.jpg",
      "original_large": "https://cdn.clopos.com/omega/1d76f22b-.../original_large.jpg",
      "thumb": "https://cdn.clopos.com/omega/1d76f22b-.../thumb.jpg"
    },
    "blur_hash": "LEIpFsE%t1}TxpENEgaK0iowRktQ",
    "dimensions": {
      "width": 612,
      "height": 459
    }
  }
]
```

| Field                 | Type              | Description                                                                                            |
| --------------------- | ----------------- | ------------------------------------------------------------------------------------------------------ |
| `uuid`                | string            | Unique identifier for the media file. Stable across URL changes.                                       |
| `mime_type`           | string            | MIME type (e.g. `"image/jpeg"`, `"image/png"`).                                                        |
| `size`                | integer           | File size in bytes.                                                                                    |
| `urls`                | object            | Available image URLs at different sizes.                                                               |
| `urls.original`       | string            | Full-resolution image.                                                                                 |
| `urls.extra_large`    | string            | Extra-large variant.                                                                                   |
| `urls.original_large` | string            | Large variant. Present on some resources (e.g. products).                                              |
| `urls.thumb`          | string            | Thumbnail (smallest variant).                                                                          |
| `blur_hash`           | string (nullable) | [BlurHash](https://blurha.sh/) placeholder string for progressive loading, or `null` if not generated. |
| `dimensions`          | object            | Image dimensions.                                                                                      |
| `dimensions.width`    | integer           | Width in pixels.                                                                                       |
| `dimensions.height`   | integer           | Height in pixels.                                                                                      |

<Note>
  Not all `urls` variants are present on every resource — the set depends on the upload configuration. Always check for the key before using it. `urls.original` and `urls.thumb` are the most reliable.
</Note>

### Tips

* Use `urls.thumb` for list views and `urls.original` for detail/full-screen views.
* `blur_hash` can be decoded client-side into a small placeholder image to show while the real image loads. See [blurha.sh](https://blurha.sh/) for libraries.
* `media` is always an array. An empty array (`[]`) means no images have been uploaded.

***

## Payment method (in receipts)

When payment methods appear inside receipt objects (e.g. in `payment_methods[]`), they use a compact shape:

```json theme={null}
"payment_methods": [
  {
    "id": 1,
    "name": "Cash",
    "amount": 33
  }
]
```

| Field    | Type    | Description                                                                                                   |
| -------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `id`     | integer | Payment method ID. Matches the `id` from [List Payment Methods](/api-reference/v2/sales/get-payment-methods). |
| `name`   | string  | Display name of the payment method.                                                                           |
| `amount` | number  | Amount tendered via this method.                                                                              |

This is a denormalized snapshot — `id` and `name` are copied at the time the receipt is closed so the receipt remains self-contained even if the payment method is later renamed or deleted.