List sales

GET/v1/sales

Sales received from the gateways in the period, paginated, with totals for the whole filter — not just the page.

Parameters

Parameter	Type	Default	Notes
`from`	YYYY-MM-DD	30 days ago	window start
`to`	YYYY-MM-DD	today	inclusive
`limit`	1–200	50	page size
`cursor`	opaque	—	from the previous nextCursor
`convertTo`	ISO-4217	—	converts the totals to a single currency — see below

Example

curl "https://public-api.passkey.global/v1/sales?from=2026-08-01&to=2026-08-31&limit=50" \
  -H "Authorization: Bearer passkey_prd_..."

json

{
  "sales": [
    {
      "id": "sale_3f8a1c2e9b7d4a6f5e01",
      "gateway": "digistore24",
      "status": "DISPATCHED",
      "eventStatus": "paid",
      "amountCents": 29900,
      "currency": "BRL",
      "orderId": "DS-88213",
      "contentId": "A7K2M9P4",
      "advertiser": {
        "id": "7291845003219",
        "name": "Conta Principal",
        "businessCenter": "BC Matriz"
      },
      "receivedAt": "2026-08-06T12:00:00.000Z",
      "dispatchedAt": "2026-08-06T12:00:03.412Z"
    }
  ],
  "total": 168,
  "nextCursor": "MjAyNi0wOC0wNlQxMjowMDowMC4wMDBa",
  "from": "2026-08-01",
  "to": "2026-08-31",
  "totals": { "paidCount": 152, "waitingCount": 9, "refundedCount": 6, "failedCount": 1 },
  "revenue": [{ "currency": "BRL", "amountCents": 4544800 }],
  "refundedRevenue": [{ "currency": "BRL", "amountCents": 179400 }],
  "netRevenue": [{ "currency": "BRL", "amountCents": 4365400 }],
  "conversion": null
}

Fields

Field	Notes
`id`	stable and prefixed. Use it as the key in your database
`gateway`	which gateway sent the sale. The list lives at `GET /v1/gateways`
`amountCents`	integer in cents, always alongside currency
`orderId`	the order id at the gateway. May be null
`contentId`	catalog item of the sale: sku_id on TikTok, retailer_id on Meta. Null = unattributed
`advertiser`	ad account behind the click. A null name means the account is not connected here, but the id still traces
`dispatchedAt`	null while no dispatch has happened

Totals cover the window

total, revenue, refundedRevenue and netRevenue cover the whole filter, not the page. That is what lets your dashboard match the gateway without paging through everything.

The filter is the period you asked for, not the page that came back. Asked for August 1 to 31 and the window has ten pages? All four numbers cover the 31 days and are identical on every page — only sales[] changes.

netRevenue can be negative — a window that only received a refund for an older sale has a negative net. Clamping it to zero would misreport the period.

convertTo

The value is the three-letter ISO-4217 code of the target currency — the same standard you already see in each sale currency field. Just append it to the query string:

text

GET /v1/sales?from=2026-08-01&to=2026-08-31&convertTo=BRL

Currency	Code
Brazilian real	`BRL`
US dollar	`USD`
Euro	`EUR`
Pound sterling	`GBP`
Mexican peso	`MXN`
Argentine peso	`ARS`

The table is just a shortcut: any three-letter ISO-4217 code is accepted, and the rate source covers around 160 currencies. A malformed code is a 400.

In the response, revenue, refundedRevenue and netRevenue stop having one entry per currency and get a single one, and conversion says where the rates came from:

json

{
  "revenue": [{ "currency": "BRL", "amountCents": 5216300 }],
  "refundedRevenue": [{ "currency": "BRL", "amountCents": 201800 }],
  "netRevenue": [{ "currency": "BRL", "amountCents": 5014500 }],
  "conversion": { "target": "BRL", "quotedFrom": "2026-08-01", "quotedTo": "2026-08-31" }
}

The conversion applies to the totals. Each sale in sales[] keeps the amountCents and currency the gateway reported — a sale amount is a fact, not a calculation.

The same rules as the other endpoints apply: each sale own day rate, all or nothing — if one day rate is missing the whole conversion is dropped and the response comes back split by currency, with conversion: null. Null never means rate 1.

Pagination

nextCursor is opaque: send back exactly what you received. null means you reached the end.

Do not build the cursor yourself. An unreadable cursor is a 400, never a silent first page — that way a bug on your side surfaces instead of duplicating data.