Search sales

/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

Authorization

Use one of the following alternatives:

apiKey
oauth2 with scopes sales.read

Authorization guide

Path parameters

merchant_codestringrequired
maxLength: 30
The merchant code.

Example: "MCZM9TGQ"

Body parameters

application/jsonrequired

start_datestring
format: date-time
Sale created on or after this instant (inclusive).

Example: "2026-06-01T00:00:00Z"
end_datestring
format: date-time
Sale created on or before this instant (inclusive).

Example: "2026-06-02T23:59:59Z"
sale_statusesarray<string>
Options:"CLOSED"
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.

Example: ["CLOSED"]
payment_statusesarray<string>
Options:"PAID""CHARGED_BACK"
Filters rows by payment outcome. Multiple values match any of them (OR). The search row does not echo this value.

Example: ["PAID"]
sales_channelsarray<string>
Options:"POS""ONLINE_PAYMENTS""KIOSK""ONLINE_STORE""SOLO""ORDER_AND_PAY""INVOICE""BOOKINGS""ORDER_AGGREGATOR""SUBSCRIPTIONS""UNKNOWN"
Sales channel filter. Multiple values match any of them (OR).

Example: ["POS"]
pagination_tokenstring
Opaque token from the previous search response. To load the next page, send it with the same filters. Not interchangeable with tokens from GET /sales.

Example: "66bcbtzelrubzeuzruzgu76678trncH"
pagination_limitinteger
minimum: 1maximum: 25default: 10
Maximum number of results per page.

Example: 10

Request examples

Search point-of-sale sales in a date range

{
  "start_date": "2026-06-01T00:00:00Z",
  "end_date": "2026-06-02T23:59:59Z",
  "sales_channels": [
    "POS"
  ],
  "pagination_limit": 10
}

Responses

200application/json

Successful response with search results.

itemsarray<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"}]
Show 9 properties
- idstringrequired
  Sale identifier.
  
  Example: "dbe3178d-4b83-5024-9b26-9b8e1b280514"
- statestringrequired
  Options:"CLOSED"
  Lifecycle state of the sale. Non-finalised sales are never returned; only fully-paid sales.
  
  Example: "CLOSED"
- tax_modestringrequired
  Options:"NO_TAX""GROSS""NET"
  Checkout tax mode for the sale. Same values as Sale.tax_mode.
  
  Example: "NO_TAX"
- currencyobjectrequired
  The currency of the sale.
  
  Show 2 properties
  codestringrequired
  format: iso-4217minLength: 3maxLength: 3
  3-letter currency code as defined by ISO-4217.
  
  Example: "EUR"
  scaleintegerrequired
  The scaling factor to apply to the value to arrive at the currency's major unit. Providing a scale mitigates changes to the minor unit over time, for example due to inflation. For example, if scale is denoted by s and value is denoted by v is the value, then one arrives at the major currency value by calculating v / 10^s.
  
  Example: 2
- total_amountintegerrequired
  format: int64
  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
- created_atstringrequired
  format: date-time
  Instant when the sale was created.
  
  Example: "2026-06-01T14:30:00Z"
- closed_atstringrequired
  format: date-time
  Instant when the sale was closed. Always present: non-finalised sales are never returned.
  
  Example: "2026-06-01T14:35:00Z"
- user_idstring
  format: uuid
  Identity UUID of the cashier who processed the sale. Omitted when the cashier identity is unknown.
  
  Example: "d6f51684-519b-454c-bdb3-deeb05f52b92"
- namestring
  Display name of the sale when set; otherwise a concatenation of item names with quantities. Omitted when neither is available.
  
  Example: "Order 1234"
pagination_tokenstring
Opaque token for the next page. Pass it as pagination_token in the next search request body with the same filters. Omitted when no further page is available.

Example: "66bcbtzelrubzeuzruzgu76678trncH"

400application/problem+json

Validation error on the request.

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

401application/problem+json

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

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

403application/problem+json

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

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

412application/problem+json

User-Agent header is not present or is empty.

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

Code sample

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",
  "sales_channels": [
    "POS"
  ],
  "pagination_limit": 10
}
'

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"

import SumUp from "@sumup/sdk";

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

  const result = await client.sales.search(
    "MCZM9TGQ",
    {
      "start_date": "2026-06-01T00:00:00Z",
      "end_date": "2026-06-02T23:59:59Z",
      "sales_channels": [
        "POS"
      ],
      "pagination_limit": 10
    }
  );
  console.log(result);
}

main().catch(console.error);

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.SearchAsync(
            "your-merchant-code",
            new SaleSearchRequest
            {
                EndDate = DateTimeOffset.Parse("2026-06-02T23:59:59Z"),
                PaginationLimit = 10,
                SalesChannels = new SalesChannelFilterV10[]
                {
                    SalesChannelFilterV10.Pos,
                },
                StartDate = DateTimeOffset.Parse("2026-06-01T00:00:00Z"),
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

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

    var result = client.sales().search(
            "MCZM9TGQ",
            com.sumup.sdk.models.SaleSearchRequest.builder()
                .endDate(java.time.OffsetDateTime.parse("2026-06-02T23:59:59Z"))
                .paginationLimit(10L)
                .salesChannels(java.util.List.of(com.sumup.sdk.models.SalesChannelFilterV10.of("POS")))
                .startDate(java.time.OffsetDateTime.parse("2026-06-01T00:00:00Z"))
                .build()
        );
    System.out.println(result);
  }
}

import os

import sumup

client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
result = client.sales.search(
    "MCZM9TGQ",
    start_date="2026-06-01T00:00:00Z",
    end_date="2026-06-02T23:59:59Z",
    sales_channels=[
        "POS",
    ],
    pagination_limit=10,
)
print(result)

<?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,
    'sales_channels' => [
        'POS',
    ],
    'start_date' => '2026-06-01T00:00:00Z',
];

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

var_dump($result);

package main

import (
	"context"
	"fmt"
	"time"

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

func main() {
	client := sumup.NewClient()
	result, err := client.Sales.Search(context.TODO(), "MCZM9TGQ", sumup.SalesSearchParams{
		EndDate:         new(time.Date(2026, time.June, 2, 23, 59, 59, 0, time.UTC)),
		PaginationLimit: new(10),
		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)
}

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::SearchRequest::builder()
        .end_date("2026-06-02T23:59:59Z".parse().expect("valid date"))
        .pagination_limit(10i64)
        .sales_channels(vec![sumup::resources::sales::SalesChannelFilterV10::Pos])
        .start_date("2026-06-01T00:00:00Z".parse().expect("valid date"))
        .build();
    let response = client
        .sales()
        .search("MERCHANT_CODE", body)
        .await
        .expect("search request failed");
    println!("{response:#?}");
}

Response example

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

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