Overview

BILLZ 2.0 Public API 2026.08

Public REST API of BILLZ 2.0 for integrations (eCommerce, marketplaces, BI, bots). ## Authentication

Create an integration key in the UI: Settings → Company settings → Integration keys.
POST /v1/auth/login with the body {"secret_token": "<key>"} → access_token + refresh_token.
All other requests: the Authorization: Bearer <access_token> header.
When the access token expires — POST /v2/auth/refresh with refresh_token. Only this method requires the platform-id header with the value 7d4a4c38-dd84-4902-b744-0488b80a4c01; other methods do not need it. Reusing an already used refresh token revokes the entire session family. ## Synchronous and asynchronous methods Some methods (sale creation, customer balance changes, warehouse operations) are executed asynchronously: the response 200 {"message": "<correlation_id>"} means that the request has been accepted, not that the operation has completed. To wait for the result in the same HTTP response, pass Billz-Response-Channel: HTTP — as a header or as the query parameter ?Billz-Response-Channel=HTTP. The maximum wait is 600 seconds, after which 408 with error.code = TIMEOUT is returned; for Excel report exports the wait is shorter — 100 seconds. Which methods are asynchronous is marked on each method. ## Permissions The integration key opens the basic methods. Sensitive methods require granted permissions (key role + permissions in sections), otherwise — 403. ## Limitations

Rate limit at the perimeter: about 2 requests per second from a single IP; when exceeded — 429.
Serving product photos directly from the BILLZ CDN to third-party sites is prohibited — cache media locally.
There are no IP/geo restrictions, but the heuristic traffic analyzer may block an IP on signs of DDoS or bot traffic.

BILLZ API changes

Information

JWT access token obtained via POST /v1/auth/login. Lifetime — 15 days.

Security scheme type: http

Bearer format: JWT