--- title: "Search 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, 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, 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, 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 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_limit` (`SearchSalesV10.pagination_limit`; integer, optional) — Maximum number of results per page. - min 1; max 25; default `10`; example `10` ## Example requests ### Search point-of-sale sales in a date range ```json { "start_date": "2026-06-01T00:00:00Z", "end_date": "2026-06-02T23:59:59Z", "sales_channels": [ "POS" ], "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.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); ``` ### .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.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); } } ``` ### Java ```java 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); } } ``` ### Python ```python 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 ```php '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); ``` ### Go ```go 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) } ``` ### 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::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:#?}"); } ``` ### cURL ```bash curl --request POST \ --url https://api.sumup.com/v1.0/merchants/MCZM9TGQ/sales/search \ --header 'Authorization: Bearer ' \ --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 } ' ``` ## 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, 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`; object, required) — The currency of the sale. - `code` (`SearchSalesV10.response.200.items.currency.code`; string, required) — 3-letter currency code as defined by ISO-4217. - format `iso-4217`; minLength 3; maxLength 3; example `"EUR"` - `scale` (`SearchSalesV10.response.200.items.currency.scale`; integer, required) — 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_amount` (`SearchSalesV10.response.200.items.total_amount`; integer, 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. - format `int64`; example `1250` - `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. Pass it as `pagination_token` in the next search request body with the same filters. Omitted when no further page is available. - 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/index.md