GET /v1/invoices
List the store's POS invoices 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/invoices" \
-H "Authorization: Bearer $PUBLIC_API_KEY"Parameters
| Name | In | Type | Description |
|---|---|---|---|
fields | query | string | Comma-separated invoices 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. |
limit | query | integer | How many invoices 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 filters. Omit for the first page; an empty nextCursor means the last page. At most 512 characters. Pattern: ^WyJ[A-Za-z0-9_-]{1,509}$ |
modifiedSince | query | string (date-time) | Only invoices modified at or after this RFC3339 timestamp (incremental sync; compare with modifiedAt). A store whose POS keeps no invoice modification time answers 422 modified_since_unsupported. |
dueFrom | query | string (date) | Only invoices due on or after this day (YYYY-MM-DD, the store's calendar). Must not be after dueTo. |
dueTo | query | string (date) | Only invoices due on or before this day (YYYY-MM-DD, inclusive: a due time of day on that day still counts). |
status | query | string | Only invoices with exactly this POS status, matched without regard to case (the POS writes Created, Picked, Completed and Processed; a store may use others). 1-25 letters, digits, spaces or . _ - At most 25 characters. Pattern: ^[A-Za-z0-9][A-Za-z0-9 ._-]{0,24}$ |
externalId | query | string | Only invoices carrying exactly this external order id (the placing system's own id, as the POS stored it; the POS strips leading zeros). Stores below TisWin3 database version 1.324 keep no external id and answer 422 filter_unsupported. At most 128 characters. Pattern: ^[A-Za-z0-9][A-Za-z0-9._:#@+-]{0,127}$ |
processorCode | query | string | Only invoices placed by this system, matched without regard to case; orders placed through POST /v1/orders carry CDAPI:<integration id>. The POS keeps only the first characters of each value (10 of the processor code and 25 of the external id on current TisWin3 databases); the store compares what you send the way the POS stored it, so the full values you sent at intake work. Stores below TisWin3 database version 1.324 answer 422 filter_unsupported. At most 50 characters. Pattern: ^[A-Za-z0-9][A-Za-z0-9 ._:#&+@-]{0,49}$ |
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 POS invoice headers in a stable order, with the cursor for the next page. | InvoiceListResponse |
400 | limit is not a whole number of 1 or more, cursor is not one a previous page issued, modifiedSince is not an RFC3339 timestamp, dueFrom or dueTo is not a YYYY-MM-DD day or dueFrom is after dueTo, or status, externalId or processorCode is not of the documented shape (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 | The API key is not enabled for this endpoint. | 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 invoices (rejected before billing). modified_since_unsupported: the store's POS keeps no invoice modification time; list without modifiedSince. filter_unsupported: the store's POS has no column to answer one of the filters (dueFrom / dueTo, status, externalId, processorCode; the last two exist only from TisWin3 database version 1.324); list without it. invoices_unsupported: the store keeps its orders in legacy tables the invoice reads cannot answer. 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 invoice 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 | invoiceId, number, orderNumber, customerId, anonymousCustomer, date, due, status, payType, orderDept, deliveryMethod, deliveryTime, route, routeSeq, processorCode, externalId, source, totals, taxRate1, taxRate2, timeline, modifiedAt |
|---|---|
| Standard set | invoiceId, number, orderNumber, customerId, anonymousCustomer, date, due, status, payType, orderDept, deliveryMethod, deliveryTime, route, routeSeq, processorCode, externalId, source, totals, taxRate1, taxRate2, timeline, modifiedAt |
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. |