---
title: "Searches sales"
method: POST
path: "/v1.0/merchants/{merchant_code}/sales/search"
tags: ["Sales"]
---

# Searches 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: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://api.sumup.com/authorize`
    - Token URL: `https://api.sumup.com/token` scopes: `sales.read`

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`.

## Path parameters

- `merchant_code` string, required

## Request body

- SaleSearchRequest: Filter and pagination criteria for `POST /sales/search`. 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`). Results are sorted **newest first** by sale close date.
  - `start_date` string, date-time: Sale created **on or after** this instant (inclusive).
  - `end_date` string, date-time: Sale created **on or before** this instant (inclusive).
  - `sale_statuses` SaleStateV10[]: 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_statuses` PaymentStatusFilterV10[]: Filters rows by payment outcome. Multiple values match any of them (**OR**). The search row does not echo this value.
  - `sales_channels` SalesChannelFilterV10[]: Sales channel filter. Multiple values match any of them (**OR**).
  - `pagination_token` string: Opaque pagination token from a previous search response. Not interchangeable with tokens from `GET /sales`.
  - `pagination_limit` integer: Maximum number of results per page.

## Response `200`

Successful response with search results.

- SaleSearchResponse: Search hits and an optional pagination token. Results are ordered **newest first** by sale close date.
  - `items` SaleSearchItem[], required
    - `id` string, required: Sale identifier.
    - `user_id` string, uuid: Identity UUID of the cashier who processed the sale. Omitted when the cashier identity is unknown.
    - `state` 'CLOSED', required: Lifecycle state of the sale. Non-finalised sales are never returned; only fully-paid sales.
    - `name` string: Display name of the sale when set; otherwise a concatenation of item names with quantities. Omitted when neither is available.
    - `tax_mode` 'NO_TAX' | 'GROSS' | 'NET', required: The tax mode used by merchant for displaying prices and calculating taxes: - NO_TAX: The prices don't contain any taxes, merchant don't report taxes - GROSS: The prices used by merchant already include taxes (common in EU), the tax is calculated from the gross price - NET: The prices used by merchant don't include taxes (common in US), the tax is calculated from the net price Since tax values can be different for the same net price depending if the tax was calculated from gross or net price, this info is necessary to be able to reconcile tax calculations.
    - `currency` 'BRL' | 'CHF' | 'CLP' | 'COP' | 'CZK' | 'DKK' | 'EUR' | 'GBP' | 'HRK' | 'HUF' | 'NOK' | 'PLN' | 'RON' | 'SEK' | 'USD', required: Three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the amount.
    - `total_amount` Amount, required
      - `currency` string, required: Currency ISO 4217 code
      - `value` integer, required: Amount in minor units (e.g. cents).
    - `created_at` string, date-time, required: Instant when the sale was created.
    - `closed_at` string, date-time, required: Instant when the sale was closed. Always present: non-finalised sales are never returned.
  - `pagination_token` string: Opaque token for the next page of search results.

## Other responses

- `400`: Validation error on the request.
- `401`: The client is not authenticated (auth header is empty or invalid).
- `403`: Missing `sales.read`, merchant code mismatch on the token, or no `merchant_read` permission.
- `412`: User-Agent header is not present or is empty.

## Changes

- **2026-11-03** `38138e18acd1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sumup/apis/sumup-rest-api/changes/v1.0/merchants/:merchant_code/sales/search/post.md)

---

[API](https://skmtc.dev/sumup/apis/sumup-rest-api.md) - [All operations](https://skmtc.dev/sumup/apis/sumup-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sumup/apis/sumup-rest-api/revisions/38138e18acd1?raw)