GET /v1/tickets
List the store's register tickets live
| Key | Required. See Authentication. |
|---|---|
| Capability | sales-data |
| Scope | sales.read |
| Price | 1 credit, per page of 100 rows returned. How pricing works. |
| Estimate | Add estimate=true for a free quote. With estimate=true the 200 body is EstimateResponse (a priced quote for exactly this request), not the schema documented under responses.200; nothing is reserved or dispatched. |
| Paging | Follow nextCursor. See Paging. |
Example
curl -s "https://api.compudime.com/v1/tickets" \
-H "Authorization: Bearer $PUBLIC_API_KEY"Parameters
| Name | In | Type | Description |
|---|---|---|---|
fields | query | string | Comma-separated register tickets fields to include (see x-compudime-field-catalog), or * for every field the key may see. Omitted: a flat-priced endpoint returns every field; once IT prices the endpoint by field count (includedFields in x-compudime-pricing), an omitted fields returns the standard set at the base price and each field beyond the included count adds extraFieldCost. An unknown or denied field is a free 400 field_not_allowed. |
from required | query | string (date) | First business day to read (YYYY-MM-DD, the store's calendar), inclusive. Required. A ticket's business day is the day the POS assigned it (a ticket rung after midnight, before the register's close time, belongs to the day before), else its date. |
to required | query | string (date) | Last business day to read (YYYY-MM-DD), inclusive. Required; not before from. Any span. The store reads tickets 31 days at a time, so a longer range is read in 31-day stretches counted from from, in date order (the tickets of each stretch in ticket id order), one after another until the answer holds limit tickets or the range ends (there is no time limit on reading, PAPI-PAGE-007); a page can still end early while nextCursor is set, when this API or the store is busy with other long answers. Keep following nextCursor until it is empty. |
register | query | string | Only the tickets of this register: its code as the rows show it (register), 1-2 letters or digits. A one-digit code and the same digit with a leading 0 name the same register (1 and 01), as the register itself treats them. Pattern: ^[A-Za-z0-9]{1,2}$ |
type | query | string | Ticket types to read: a comma-separated list of the TicketHD type letters S, O, V, T, R, G, H and A (either case), each at most once. Omitted: the sale types S and O. Only the two sale types are read unless type names others: S (a completed register sale) and O (a direct account charge or payment, which normally carries a sale of 0). The other types are not sales and must never be summed as revenue: V a voided sale (its sale total is still filled in), T calculate-only or a transfer whose value already landed on another ticket (it would double-count), R a transfer ticket not yet paid, G training mode, H a held sale and A a sale still being rung. Compare with type and sale on a row. Pattern: ^[SOVTRGHAsovtrgha](,[SOVTRGHAsovtrgha]){0,7}$ |
limit | query | integer | How many tickets to return: any whole number of 1 or more; default 100 (one page). The store is read 200 at a time, so a larger limit is read from the store in several reads, one after another, and answered at once. One answer carries at most 10,000 (a safeguard on the size of one answer, not a limit on the listing); a larger limit ends with nextCursor. There is no time limit on reading: an answer that needs several reads keeps reading until it holds limit rows (at most 10,000) or the listing ends. While it reads, the response is already open: its body starts with spaces (legal JSON whitespace, sent every few seconds so no proxy closes an idle connection), and X-Credits-Charged and X-Credits-Remaining are not response headers but HTTP trailers, which reach HTTP/2 clients (on api.compudime.com and compudime-public-api.fly.dev alike) and are dropped over HTTP/1.1. The billing block in the body always says what the call cost (totalCredits per unit times quantity); /v1/usage/current gives the balance. When this API or the store is busy with other long answers, an answer may end after its first read with nextCursor instead. A page can hold fewer rows than limit while nextCursor is set: keep following nextCursor until it is empty. Default: 100. At least 1. |
cursor | query | string | nextCursor from the previous page, verbatim, with the same from, to, register and type: a cursor continues only the listing it came from, and any other is a free 400. Omit for the first page; an empty nextCursor means the last page. At most 1024 characters. Pattern: ^[A-Za-z0-9_-]{1,1024}$ |
estimate | query | boolean | When true, returns EstimateResponse instead of the normal body and never reserves credits: the request is authenticated, authorized and field-resolved exactly like a real call, then priced by billing (base cost plus extra-field credits for the resolved fields) and returned without dispatching to the store. Free of charge. Default: false. |
Responses
| Status | Description | Body |
|---|---|---|
200 | One live page of the store's register ticket headers of a business-day range in a stable order, with the cursor for the next page. | TicketListResponse |
400 | from or to is missing or not a YYYY-MM-DD day, to is before from, register or type is not of the documented shape, limit is not a whole number of 1 or more, cursor is not one a previous page of this very listing issued (the same from, to, register and type), or modifiedSince was sent (the POS keeps no ticket modification time an incremental read could trust) (code bad_request); or a requested field is not allowed (code field_not_allowed). Rejected before billing. | Problem |
401 | Public API key is missing, invalid, or revoked. | Problem |
402 | The request was blocked by billing policy: no_api_plan (no plan funds this meter), billing_card_missing, billing_card_failed, usage_exhausted, overage_cap_reached, subscription_paused, sandbox_exhausted, or billing_blocked. A key the store pays for under its approval gets grant_cap_exceeded (the store's monthly limit for your calls) or payer_billing_blocked (the store cannot be charged right now; ask the store owner) instead: what is wrong with the store's billing is not shown to it. | Problem |
403 | capability_not_enabled: the API key is not a sales-data key with the sales.read scope (rejected before billing). store_feature_not_enabled: the key is entitled, but the store has not turned on per-item data for developers on its own POS agent (the same store switch as sales movement and the invoice reads); nothing changes until the store enables it. The reservation is released, nothing is charged. | Problem |
405 | The requested method is not allowed for this endpoint. | Problem |
422 | scope_not_applicable: the API key carries a row scope, and no row scope can be applied to a register ticket or a register log (rejected before billing). agent_update_required: the store's CompuDime agent is older than these reads; the store must update it. tickets_unsupported: the store's POS database has no register ticket tables with the columns these reads need. The reservation is released, nothing is charged. | Problem |
429 | Too many requests from this API key (code rate_limited). Each key has its own request budget at the API edge, refilled continuously; it covers every authenticated endpoint, including the free ones, and is checked before anything is billed or sent to the store. Billed endpoints are also subject to the store plan's per-minute ceiling, which answers the same problem code. Wait at least Retry-After seconds before the next request with this key, then resume; if 429 answers again, back off exponentially (double the wait each time, up to a minute or so) and add random jitter so parallel workers do not retry in step. A 429 is never charged and reserves nothing. Header Retry-After: Whole seconds to wait before retrying with this key: the time until the key's next request token at the edge (never less than 1), or 60 when the store plan's per-minute ceiling refused the call. | Problem |
500 | The API edge encountered an internal error. | Problem |
502 | The store's POS could not complete the ticket list (code store_error): the agent answered an error, the store has not enabled per-item data for developers, or the agent or relay build predates this operation. The reservation is released. | Problem |
503 | The store's POS agent is offline (code store_offline), or a Public API dependency is unavailable. The reservation is released. Also answered, with code endpoint_disabled, while CompuDime has temporarily switched the endpoint off: the whole API, the endpoint's family (x-compudime-family) or this endpoint alone; the detail says which and why. It is checked before anything is validated, reserved or sent to the store, so it is never charged; it is retryable and carries Retry-After. Header Retry-After: Sent with code endpoint_disabled: whole seconds to wait before asking again. A switch has no scheduled end, so this is a polling interval (60), not a promise. | Problem |
504 | The store did not answer inside the read ceiling (code store_timeout). The reservation is released. | Problem |
Error bodies are problem JSON; every code is listed there.
Fields
Choose with fields=; see Choosing fields.
| All fields | ticketId, register, type, sale, businessDay, date, time, createdAt, finishedAt, logNumber, customerId, anonymousCustomer, payType, totals, ticketDiscountPercent, customerDiscountPercent, taxExempt, taxRate1, taxRate2, priceLevel, paperBagCount, upChargePercent |
|---|---|
| Standard set | ticketId, register, type, sale, businessDay, date, time, createdAt, finishedAt, logNumber, customerId, anonymousCustomer, payType, totals, ticketDiscountPercent, customerDiscountPercent, taxExempt, taxRate1, taxRate2, priceLevel, paperBagCount, upChargePercent |
Access level
What your integration's access level changes here.
| Level | Scope | Effect |
|---|---|---|
own | sales.read | The level does not change this operation: own and all return the same data. |
all | sales.read | The level does not change this operation: own and all return the same data. |