Customer purchases

POST

/v1/customer-purchases-report-excel

curl --request POST \
  --url 'https://api-admin.billz.ai/v1/customer-purchases-report-excel?Billz-Response-Channel=HTTP' \
  --header 'Authorization: Bearer <token>' \
  --header 'Billz-Response-Channel: HTTP' \
  --header 'Content-Type: application/json' \
  --header 'platform-id: 7d4a4c38-dd84-4902-b744-0488b80a4c01' \
  --data '{ "shop_ids": [ "2339a738-a67f-48d2-bb60-8cf4ec54d6cd" ], "start_date": "2026-08-01", "end_date": "2026-08-31", "with_customers": true, "currency": "UZS", "fields": [ "created_at", "customer_name", "product_name", "gross_sales" ] }'

• Production

Asynchronous method. The file is built in the background. The Billz-Response-Channel: HTTP header is required: only with it does the response carry a link to the finished file, with a wait of up to 100 seconds. Without the header the response is 200 {"message": "<correlation_id>"}, and the file can no longer be fetched through the API: the link is delivered as a notification to the BILLZ interface.

A line-by-line list of purchases: what was bought, by whom and when.

Error codes: 400 — input validation error; 404 — object not found; 408 — timed out waiting for the asynchronous result; 401, 403, 429, 500 — shared by all methods. Body formats and semantics: Response codes and errors.

Authorizations

• BearerAuth

Parameters

Header Parameters

platform-id

string

default: 7d4a4c38-dd84-4902-b744-0488b80a4c01

Platform identifier. A static value is used for integrations.

Billz-Response-Channel

string

Allowed values: HTTP

HTTP — wait for the event processing result and return it in the HTTP response. Without the header the method returns only the correlation_id of the published event.

Query Parameters

Billz-Response-Channel

string

Allowed values: HTTP

Same as the Billz-Response-Channel header — for clients that cannot send a custom header. If both are passed, the header applies.

Request Body^required

Media typeapplication/json

object

start_date

Start of the period, YYYY-MM-DD

string

end_date

End of the period, YYYY-MM-DD

string

shop_ids

Shops of the report; intersected with the list of shops available to the token

Array<string>

with_customers

true — only purchases linked to a customer, false — all of them, anonymous ones included

boolean

currency

Currency in which the amounts are shown

string

price_type

Price type: 0 — all, 1 — retail, 2 — free-price, 3 — wholesale

integer format: int32

Allowed values: 0 1 2 3

group_without_shops

true — collapse the rows without a breakdown by shop

boolean

fields

The file columns in the order they appear. Without fields the file has no data columns; the list of values is in Report export to Excel

Array<string>

Example

{
  "shop_ids": [
    "2339a738-a67f-48d2-bb60-8cf4ec54d6cd"
  ],
  "start_date": "2026-08-01",
  "end_date": "2026-08-31",
  "with_customers": true,
  "currency": "UZS",
  "fields": [
    "created_at",
    "customer_name",
    "product_name",
    "gross_sales"
  ]
}

Responses

200

Success. With the Billz-Response-Channel: HTTP header — the asynchronous response envelope with a link to the file, without it — {"message": "<correlation_id>"}.

Media typeapplication/json

One of:

object

Asynchronous response envelope. Returned when the Billz-Response-Channel: HTTP header is passed. The final HTTP code of the request is taken from the status_code field.

object

session_id

Customer session identifier

string format: uuid

status_code

Event processing status (also the final HTTP response code)

integer

error

object

code

Error code, empty string if there is no error

string

message

Error text, empty string if there is no error

string

correlation_id

Request identifier, matches the ID of the published event

string format: uuid

topic

Response event type, for example <event_type>.success

string

data

Operation result, if the method returns one

object

object

Response of an asynchronous method without the Billz-Response-Channel header — the event has been published.

object

message

Correlation_id of the published event

string format: uuid

object

The asynchronous response envelope with a link to the finished file.

object

status_code

integer format: int32

error

object

code

string

message

string

correlation_id

string format: uuid

data

object

filename

File name without the extension

string

url

Link to the finished file; it carries no extension, the content is .xlsx

string

session_id

string

topic

string

Example^generated

{
  "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "status_code": 1,
  "error": {
    "code": "example",
    "message": "example"
  },
  "correlation_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "topic": "example",
  "data": {}
}