Skip to content
BILLZ for developers

Salesperson summary

POST
/v1/seller-general-report-excel
curl --request POST \
  --url 'https://api-admin.billz.ai/v1/seller-general-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", "currency": "UZS", "price_type": 1, "hide_sellers_without_sales": true, "detalization": "day", "fields": [ "date", "seller_name", "gross_sales", "net_gross_profit", "transaction_count" ] }'

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.

Sales broken down by salesperson. The report is always built for all salespeople of the company — the method has no filter by specific salespeople.

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

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “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

Section titled “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 Bodyrequired

Section titled “Request Bodyrequired”
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>
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
detalization

Grouping of rows by period

string
Allowed values: 30min hour day week month year
hide_sellers_without_sales

true — exclude salespeople with no sales and no returns over the period

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",
  "currency": "UZS",
  "price_type": 1,
  "hide_sellers_without_sales": true,
  "detalization": "day",
  "fields": [
    "date",
    "seller_name",
    "gross_sales",
    "net_gross_profit",
    "transaction_count"
  ]
}

Responses

Section titled “Responses”

200

Section titled “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:

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
Examplegenerated
{
  "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": {}
}