Перейти к основному содержимому

List orders

GET 
/api/v1/orders

Lists orders for the current API key. Supports pagination and optional filtering.

Filters:

  • orderId: internal order id (must be a valid UUID)
  • referenceId: partner reference id / idempotency key

Voucher codes are returned masked by default (**** + last 4 characters). To retrieve full codes, set unhide=true only together with orderId or referenceId. When unhide=true, codes are marked as received in the underlying shop service and the first retrieval timestamp is stored.

Rate-limit buckets​

GET /rate-limits reports five variants. Listing and masked polling use per-account counters; unhide counters are per account and canonical order:

  • GET /orders — unfiltered listing (no filters set). Tight bucket, intended for ad-hoc inspection only. Default 2/min.
  • GET /orders (filtered) — orderId or referenceId set, unhide not set. Use this for status-only polling with masked codes. Default 60/min across orders on the account.
  • GET /orders (unhide pending) — unhide=true while the selected order is IN_PROGRESS or PARTIALLY_COMPLETED: default 60/min per canonical order.
  • GET /orders (unhide completed) — unhide=true with SUCCESS or CANCELLED: default 1/min per canonical order, including cached-code retries. Pending polls do not consume the completed budget.
  • GET /orders (unhide admission) — bounds upstream reads before checking live state. Derived from the sum of the two limits and greatest common divisor of their windows (61/60s by default). After 60 pending replies the next request can deliver a completed reply; if still pending it returns 429 and further reads wait for rollover.

You can poll the same filtered request with unhide=true from the start. Read the order status from data.page.items[].status, save returned codes and stop polling after a terminal result. PARTIALLY_COMPLETED is terminal partial delivery and may already contain codes, even though it uses the pending budget.

orderId and referenceId aliases share counters. Orders remain visible only to the API key that created them. For checkout references, any selected SUCCESS/CANCELLED child makes the aggregate use the completed budget; selecting a child with orderId uses its own budget. A lost completed response still consumes quota: respect Retry-After before retrying. No additional code receipt is required for cached codes.

On excess the response is HTTP 429 with statusCode=LIMIT_REACHED, statusMessage naming the bucket and configured budget, and a Retry-After header set to the window length in seconds. Effective budgets are visible in GET /api/v1/rate-limits. Without a DB rule, listing and masked polling fall back to RATE_LIMIT_DEFAULT_LIMIT / RATE_LIMIT_DEFAULT_WINDOW_SECONDS; unhide pending and completed keep their own 60/60s and 1/60s defaults, and admission is derived from those two budgets.

Empty filtered response: when a referenceId or orderId filter is set but no matching record is found, the response is items=[] and the optional page.hint field explains the likely cause (e.g. the order was created with a different API key). An unfiltered empty list (new account) has hint=null.

Request​

Responses​

Successful Response