---
title: "Searches sales"
description: "Returns a paginated list of `SaleSearchItem` rows matching filter criteria. Results are\nsorted **newest first** by **sale close date**.\n\nFilters from different categories stack with **logical AND**; multiple values in one array\nfield stack with **logical OR**. Results cover the merchant’s **last two years** of sales\n(narrow further with `start_date` / `end_date`). Pagination tokens are not interchangeable\nwith `GET /sales`.\n\n**OAuth scopes:** Requires one of: `sales.read`.\n\n**Required permissions:**\n\n- `merchant_read`"
image: "https://developer.sumup.com/og/index.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://developer.sumup.com/llms.txt
> Use this file to discover all available pages before exploring further.

Path: SumUp REST API › Sales

`POST /v1.0/merchants/{merchant_code}/sales/search`

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

**OAuth scopes:** Requires one of: `sales.read`.

**Required permissions:**

- `merchant_read`

## Authentication

Requires one of the following:

- `apiKey`, http, header `Authorization`
- `oauth2`, oauth2, scopes: `sales.read`

## Path parameters

- `merchant_code` (`SearchSalesV10.path.merchant_code`; string, required) — The merchant code.
  - maxLength 30; example `"MCZM9TGQ"`

## Request body

_Required._

- `start_date` (`SearchSalesV10.start_date`; string, optional) — Sale created **on or after** this instant (inclusive).
  - format `date-time`; example `"2026-06-01T00:00:00Z"`
- `end_date` (`SearchSalesV10.end_date`; string, optional) — Sale created **on or before** this instant (inclusive).
  - format `date-time`; example `"2026-06-02T23:59:59Z"`
- `sale_statuses` (`SearchSalesV10.sale_statuses`; array<string>, optional) — 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.
  - one of `"CLOSED"`; example `["CLOSED"]`
- `payment_statuses` (`SearchSalesV10.payment_statuses`; array<string>, optional) — Filters rows by payment outcome. Multiple values match any of them (**OR**). The search row does not echo this value.
  - one of `"PAID"`, `"CHARGED_BACK"`; example `["PAID"]`
- `sales_channels` (`SearchSalesV10.sales_channels`; array<string>, optional) — Sales channel filter. Multiple values match any of them (**OR**).
  - one of `"POS"`, `"ONLINE_PAYMENTS"`, `"KIOSK"`, `"ONLINE_STORE"`, `"SOLO"`, `"ORDER_AND_PAY"`, `"INVOICE"`, `"BOOKINGS"`, `"ORDER_AGGREGATOR"`, `"SUBSCRIPTIONS"`, `"UNKNOWN"`; example `["POS"]`
- `pagination_token` (`SearchSalesV10.pagination_token`; string, optional) — Opaque pagination token from a previous search response. Not interchangeable with tokens from `GET /sales`.
  - example `"66bcbtzelrubzeuzruzgu76678trncH"`
- `pagination_limit` (`SearchSalesV10.pagination_limit`; integer, optional) — Maximum number of results per page.
  - min 1; max 25; default `10`; example `10`

## Example request

```json
{
  "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
}
```

## Code samples

### CLI

```bash
sumup sales search \
  --merchant-code "MCZM9TGQ" \
  --pagination-limit "10" \
  --pagination-token "66bcbtzelrubzeuzruzgu76678trncH" \
  --start-date "2026-06-01T00:00:00Z" \
  --end-date "2026-06-02T23:59:59Z" \
  --sales-channel "POS"

```

### JavaScript

```typescript
import SumUp from "@sumup/sdk";

async function main() {
  const client = new SumUp({ apiKey: "sup_sk_your_api_key" });

  const result = await client.sales.searchSalesV10(
    "MCZM9TGQ",
    {
      "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
    }
  );
  console.log(result);
}

main().catch(console.error);

```

### .NET

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SumUp;

public static class Program
{
    public static async Task Main()
    {
        using var client = new SumUpClient();
        var response = await client.Sales.SearchSalesV10Async(
            "your-merchant-code",
            new SaleSearchRequest
            {
                EndDate = DateTimeOffset.Parse("2026-06-02T23:59:59Z"),
                PaginationLimit = 10,
                PaginationToken = "66bcbtzelrubzeuzruzgu76678trncH",
                PaymentStatuses = new PaymentStatusFilterV10[]
                {
                    PaymentStatusFilterV10.Paid,
                },
                SaleStatuses = new SaleStateV10[]
                {
                    SaleStateV10.Closed,
                },
                SalesChannels = new SalesChannelFilterV10[]
                {
                    SalesChannelFilterV10.Pos,
                },
                StartDate = DateTimeOffset.Parse("2026-06-01T00:00:00Z"),
            });

        Console.WriteLine(response.StatusCode);
    }
}

```

### Java

```java
import com.sumup.sdk.SumUpClient;

public final class SearchSalesV10Sample {
  public static void main(String[] args) throws Exception {
    var client = new SumUpClient();

    var result = client.sales().searchSalesV10(
            "MCZM9TGQ",
            com.sumup.sdk.models.SaleSearchRequest.builder()
                .build()
        );
    System.out.println(result);
  }
}

```

### Python

```python
import os

import sumup

client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
result = client.sales.search_sales_v_10(
    "MCZM9TGQ",
    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,
)
print(result)

```

### PHP

```php
<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

$sumup = new \SumUp\SumUp('sup_sk_your_api_key');

$body = [
    'end_date' => '2026-06-02T23:59:59Z',
    'pagination_limit' => 10,
    'pagination_token' => '66bcbtzelrubzeuzruzgu76678trncH',
    'payment_statuses' => [
        'PAID',
    ],
    'sale_statuses' => [
        'CLOSED',
    ],
    'sales_channels' => [
        'POS',
    ],
    'start_date' => '2026-06-01T00:00:00Z',
];

$result = $sumup->sales()->searchSalesV10(
    'MCZM9TGQ',
    $body,
);

var_dump($result);

```

### Go

```go
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/sumup/sumup-go"
)

func main() {
	client := sumup.NewClient()
	result, err := client.Sales.SearchSalesV10(context.TODO(), "MCZM9TGQ", sumup.SalesSearchSalesV10Params{
		EndDate:         new(time.Date(2026, time.June, 2, 23, 59, 59, 0, time.UTC)),
		PaginationLimit: new(10),
		PaginationToken: new("66bcbtzelrubzeuzruzgu76678trncH"),
		PaymentStatuses: []sumup.PaymentStatusFilterV10{"PAID"},
		SaleStatuses:    []sumup.SaleStateV10{"CLOSED"},
		SalesChannels:   []sumup.SalesChannelFilterV10{"POS"},
		StartDate:       new(time.Date(2026, time.June, 1, 0, 0, 0, 0, time.UTC)),
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("%+v\n", result)
}

```

### Rust

```rust
use sumup::{Authorization, Client};
#[tokio::main]
async fn main() {
    let client = Client::default()
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
    let body = sumup::resources::sales::SearchSalesV10Request::builder().build();
    let response = client
        .sales()
        .search_sales_v10("MERCHANT_CODE", body)
        .await
        .expect("search_sales_v10 request failed");
    println!("{response:#?}");
}

```

### cURL

```bash
curl --request POST \
  --url https://api.sumup.com/v1.0/merchants/MCZM9TGQ/sales/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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
}
'
```

## Responses

### 200

Successful response with search results.

#### Example

```json
{
  "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"
}
```

- `items` (`SearchSalesV10.response.200.items`; array<object>, required)
  - example `[{"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"}]`
  - `id` (`SearchSalesV10.response.200.items.id`; string, required) — Sale identifier.
    - example `"dbe3178d-4b83-5024-9b26-9b8e1b280514"`
  - `state` (`SearchSalesV10.response.200.items.state`; string, required) — Lifecycle state of the sale. Non-finalised sales are never returned; only fully-paid sales.
    - one of `"CLOSED"`; example `"CLOSED"`
  - `tax_mode` (`SearchSalesV10.response.200.items.tax_mode`; string, required) — Checkout tax mode for the sale. Same values as `Sale.tax_mode`.
    - one of `"NO_TAX"`, `"GROSS"`, `"NET"`; example `"NO_TAX"`
  - `currency` (`SearchSalesV10.response.200.items.currency`; string, required) — Three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the amount.
    - one of `"BRL"`, `"CHF"`, `"CLP"`, `"COP"`, `"CZK"`, `"DKK"`, `"EUR"`, `"GBP"`, `"HRK"`, `"HUF"`, `"NOK"`, `"PLN"`, `"RON"`, `"SEK"`, `"USD"`; example `"EUR"`
  - `total_amount` (`SearchSalesV10.response.200.items.total_amount`; object, required) — Final sale gross total after discounts and taxes, excluding tips. Same value as `Sale.price.gross_amount`, in minor units according to `currency.scale`. Payment amounts include tips and can therefore differ from this total.
    - example `1250`
    - `currency` (`SearchSalesV10.response.200.items.total_amount.currency`; string, required) — Currency ISO 4217 code
      - example `"MXN"`
    - `value` (`SearchSalesV10.response.200.items.total_amount.value`; integer, required) — Amount in minor units (e.g. cents).
      - example `1000`
  - `created_at` (`SearchSalesV10.response.200.items.created_at`; string, required) — Instant when the sale was created.
    - format `date-time`; example `"2026-06-01T14:30:00Z"`
  - `closed_at` (`SearchSalesV10.response.200.items.closed_at`; string, required) — Instant when the sale was closed. Always present: non-finalised sales are never returned.
    - format `date-time`; example `"2026-06-01T14:35:00Z"`
  - `user_id` (`SearchSalesV10.response.200.items.user_id`; string, optional) — Identity UUID of the cashier who processed the sale. Omitted when the cashier identity is unknown.
    - format `uuid`; example `"d6f51684-519b-454c-bdb3-deeb05f52b92"`
  - `name` (`SearchSalesV10.response.200.items.name`; string, optional) — Display name of the sale when set; otherwise a concatenation of item names with quantities. Omitted when neither is available.
    - example `"Order 1234"`
- `pagination_token` (`SearchSalesV10.response.200.pagination_token`; string, optional) — Opaque token for the next page of search results.
  - example `"66bcbtzelrubzeuzruzgu76678trncH"`

### 400

Validation error on the request.

#### Example

```json
{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "instance": "http://example.com"
}
```

- `type` (`SearchSalesV10.response.400.type`; string, required) — A URI reference that identifies the problem type.
  - format `uri`; example `"https://developer.sumup.com/problem/not-found"`
- `title` (`SearchSalesV10.response.400.title`; string, optional) — A short, human-readable summary of the problem type.
  - example `"Requested resource couldn't be found."`
- `status` (`SearchSalesV10.response.400.status`; integer, optional) — The HTTP status code generated by the origin server for this occurrence of the problem.
  - example `404`
- `detail` (`SearchSalesV10.response.400.detail`; string, optional) — A human-readable explanation specific to this occurrence of the problem.
  - example `"The requested resource doesn't exist or does not belong to you."`
- `instance` (`SearchSalesV10.response.400.instance`; string, optional) — A URI reference that identifies the specific occurrence of the problem.
  - format `uri`

### 401

The client is not authenticated (auth header is empty or invalid).

#### Example

```json
{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "instance": "http://example.com"
}
```

- `type` (`SearchSalesV10.response.401.type`; string, required) — A URI reference that identifies the problem type.
  - format `uri`; example `"https://developer.sumup.com/problem/not-found"`
- `title` (`SearchSalesV10.response.401.title`; string, optional) — A short, human-readable summary of the problem type.
  - example `"Requested resource couldn't be found."`
- `status` (`SearchSalesV10.response.401.status`; integer, optional) — The HTTP status code generated by the origin server for this occurrence of the problem.
  - example `404`
- `detail` (`SearchSalesV10.response.401.detail`; string, optional) — A human-readable explanation specific to this occurrence of the problem.
  - example `"The requested resource doesn't exist or does not belong to you."`
- `instance` (`SearchSalesV10.response.401.instance`; string, optional) — A URI reference that identifies the specific occurrence of the problem.
  - format `uri`

### 403

Missing `sales.read`, merchant code mismatch on the token, or no `merchant_read` permission.

#### Example

```json
{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "instance": "http://example.com"
}
```

- `type` (`SearchSalesV10.response.403.type`; string, required) — A URI reference that identifies the problem type.
  - format `uri`; example `"https://developer.sumup.com/problem/not-found"`
- `title` (`SearchSalesV10.response.403.title`; string, optional) — A short, human-readable summary of the problem type.
  - example `"Requested resource couldn't be found."`
- `status` (`SearchSalesV10.response.403.status`; integer, optional) — The HTTP status code generated by the origin server for this occurrence of the problem.
  - example `404`
- `detail` (`SearchSalesV10.response.403.detail`; string, optional) — A human-readable explanation specific to this occurrence of the problem.
  - example `"The requested resource doesn't exist or does not belong to you."`
- `instance` (`SearchSalesV10.response.403.instance`; string, optional) — A URI reference that identifies the specific occurrence of the problem.
  - format `uri`

### 412

User-Agent header is not present or is empty.

#### Example

```json
{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "instance": "http://example.com"
}
```

- `type` (`SearchSalesV10.response.412.type`; string, required) — A URI reference that identifies the problem type.
  - format `uri`; example `"https://developer.sumup.com/problem/not-found"`
- `title` (`SearchSalesV10.response.412.title`; string, optional) — A short, human-readable summary of the problem type.
  - example `"Requested resource couldn't be found."`
- `status` (`SearchSalesV10.response.412.status`; integer, optional) — The HTTP status code generated by the origin server for this occurrence of the problem.
  - example `404`
- `detail` (`SearchSalesV10.response.412.detail`; string, optional) — A human-readable explanation specific to this occurrence of the problem.
  - example `"The requested resource doesn't exist or does not belong to you."`
- `instance` (`SearchSalesV10.response.412.instance`; string, optional) — A URI reference that identifies the specific occurrence of the problem.
  - format `uri`


Source: https://developer.sumup.com/api/sales/search-sales-v10/index.md