Searches 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 pagination token from a previous search response. Not interchangeable with tokens from GET /sales.

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

Example: 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"
- currencystringrequired
  Options:"BRL""CHF""CLP""COP""CZK""DKK""EUR""GBP""HRK""HUF""NOK""PLN""RON""SEK""USD"
  Three-letter ISO 4217 currency code of the amount.
  
  Example: "EUR"
- total_amountobjectrequired
  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
  Show 2 properties
  currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
  valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
- 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 of search results.

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",
  "sale_statuses": [
    "CLOSED"
  ],
  "payment_statuses": [
    "PAID"
  ],
  "sales_channels": [
    "POS"
  ],
  "pagination_token": "66bcbtzelrubzeuzruzgu76678trncH",
  "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.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);

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);
    }
}

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);
  }
}

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

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);

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)
}

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:#?}");
}

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