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:

{
  "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.

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

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

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.

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 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:

"payment_methods": [
  {
    "id": 1,
    "name": "Cash",
    "amount": 33
  }
]

Field	Type	Description
`id`	integer	Payment method ID. Matches the `id` from List 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.

Introduction

Concepts

Common objects

Common objects

Response envelope

Filtering

Error envelope

Media

Tips

Payment method (in receipts)

​Common objects

​Response envelope

​Pagination

​Filtering

​Error envelope

​Media

​Tips

​Payment method (in receipts)

Common objects

Response envelope

Pagination

Filtering

Error envelope

Media

Tips

Payment method (in receipts)