Skip to main content

​
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", ...]
}
FieldTypeDescription
successbooleantrue on success. Always check this first — one edge case (test/production mismatch) returns HTTP 200 with success: false.
dataobject or arrayThe requested resource(s). An object for single-resource endpoints (GET /v2/receipts/1), an array for list endpoints (GET /v2/receipts).
totalinteger(List endpoints only.) Total number of records matching the query, before pagination. Use this alongside page and limit to calculate total pages.
timeintegerServer-side response time in milliseconds. Useful for monitoring but not guaranteed to be stable — do not use for business logic.
timestampstringServer timestamp in YYYY-MM-DD HH:mm:ss format (UTC).
unixintegerSame timestamp as a Unix epoch in seconds.
sortsarray(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:
ParameterTypeDefaultDescription
pageinteger1Page number (1-based).
limitinteger50Records per page. Maximum varies by resource (typically 200).
sort[0]stringcreated_atField to sort by (must be a value from sorts).
sort[1]integer-1Sort direction: 1 = ascending, -1 = descending.

​
Filtering

Many list endpoints support date-range and field-level filters:
ParameterTypeDescription
date[0]stringStart date (inclusive), YYYY-MM-DD.
date[1]stringEnd date (inclusive), YYYY-MM-DD.
filters[N][0]stringField name to filter on.
filters[N][1]stringValue 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
    }
  }
]
FieldTypeDescription
uuidstringUnique identifier for the media file. Stable across URL changes.
mime_typestringMIME type (e.g. "image/jpeg", "image/png").
sizeintegerFile size in bytes.
urlsobjectAvailable image URLs at different sizes.
urls.originalstringFull-resolution image.
urls.extra_largestringExtra-large variant.
urls.original_largestringLarge variant. Present on some resources (e.g. products).
urls.thumbstringThumbnail (smallest variant).
blur_hashstring (nullable)BlurHash placeholder string for progressive loading, or null if not generated.
dimensionsobjectImage dimensions.
dimensions.widthintegerWidth in pixels.
dimensions.heightintegerHeight 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
  }
]
FieldTypeDescription
idintegerPayment method ID. Matches the id from List Payment Methods.
namestringDisplay name of the payment method.
amountnumberAmount 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.