SUsumup
Sales

Searches sales

Changed on

Returns a paginated list of SaleSearchItem rows matching filter criteria. Results are sorted newest first by sale close date.

Filters from different categories stack with logical AND; multiple values in one array field stack with logical OR. Results cover the merchant’s last two years of sales (narrow further with start_date / end_date). Pagination tokens are not interchangeable with GET /sales.

post/v1.0/merchants/{merchant_code}/sales/search

Request

  • Base URL
    https://api.sumup.com
  • URL
    https://api.sumup.com/v1.0/merchants/{merchant_code}/sales/search
  • Auth
    • HTTP bearer
    • or OAuth 2
      Authorization code: https://api.sumup.com/authorize
      Token URL: https://api.sumup.com/token scopes: sales.read

Path parameters

merchant_codestring required
Example:MCZM9TGQ

The merchant code.

Request body

start_datestring date-time

Sale created on or after this instant (inclusive).

end_datestring date-time

Sale created on or before this instant (inclusive).

sale_statusesSaleStateV10[]

Filters rows by sale lifecycle (state). Multiple values match any of them (OR). Uses the same values as Sale.state. Non-finalised sales are never returned; only fully-paid sales.

payment_statusesPaymentStatusFilterV10[]

Filters rows by payment outcome. Multiple values match any of them (OR). The search row does not echo this value.

sales_channelsSalesChannelFilterV10[]

Sales channel filter. Multiple values match any of them (OR).

pagination_tokenstring

Opaque pagination token from a previous search response. Not interchangeable with tokens from GET /sales.

pagination_limitinteger

Maximum number of results per page.

Example request

{
  "start_date": "2026-06-01T00:00:00Z",
  "end_date": "2026-06-02T23:59:59Z",
  "sale_statuses": [
    "CLOSED"
  ],
  "payment_statuses": [
    "PAID"
  ],
  "sales_channels": [
    "POS"
  ],
  "pagination_token": "66bcbtzelrubzeuzruzgu76678trncH",
  "pagination_limit": 10
}

Response

Successful response with search results.

pagination_tokenstring

Opaque token for the next page of search results.

Example response

{
  "items": [
    {
      "id": "dbe3178d-4b83-5024-9b26-9b8e1b280514",
      "state": "CLOSED",
      "tax_mode": "GROSS",
      "currency": {
        "code": "EUR",
        "scale": 2
      },
      "name": "Order 1234",
      "total_amount": 1250,
      "created_at": "2026-06-01T14:30:00Z",
      "closed_at": "2026-06-01T14:35:00Z"
    }
  ],
  "pagination_token": "66bcbtzelrubzeuzruzgu76678trncH"
}

Changes