Lists sales

GET/v1.0/merchants/{merchant_code}/sales

Returns a paginated list of Sale objects. Results are sorted newest first by the newest event recorded for each sale. Pagination tokens follow that order.

Covers the merchant’s last two years of sales. Non-finalised sales are never returned; only fully-paid sales. Use POST /sales/search for filtered queries.

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"

Query parameters

pagination_tokenstring
Pagination token for subsequent requests. Should only be set by clients if they have received a token in the previous response, and this request is an immediate follow-up request to that response to load the subsequent page. Clients should treat this as an opaque token and should not attempt to parse it in any way.
pagination_limitinteger
minimum: 1maximum: 25default: 10
Maximum number of results per page.

Responses

200application/json

Successful response with a page of sales.

itemsarray<object>required
Show 13 properties
- idstringrequired
  The ID of the sale.
  
  Example: "dbe3178d-4b83-5024-9b26-9b8e1b280514"
- 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"
- itemsarray<object>required
  The lines sold in this sale, in the order they were added to the cart. Includes merchant fees (type: "FEE") when present; fee details are in features.
  
  Show 12 properties
  idstringrequired
  maxLength: 100
  Stable identifier of the line within the sale. Used for linking (e.g. deposits).
  
  Example: "line-1"
  typestringrequired
  Classifies a sale line. Not a schema subclass.
  
  Known values: CATALOG, DEPOSIT, GIFT_CARD, CUSTOM, FEE.
  
  FEE lines represent merchant-charged fees on the sale (e.g. shipping, service charge, surcharge, cancellation). They participate in sale totals like any other line; type-specific data is carried in features (see Feature for the conventional feature keys).
  
  This is intentionally an open string, NOT a closed enum: new values are added over time as pure data and consumers MUST tolerate unknown values, rendering the line from the generic envelope (name, quantity, price, taxes) and reading any extra information from features.
  
  Example: "CATALOG"
  namestringrequired
  maxLength: 250
  Display name of the line.
  
  Example: "Cappuccino"
  quantitynumberrequired
  format: doubleminimum: 0
  The numerical value representing the quantity in the specified unit.
  
  Example: 2.15332
  unit_of_measureobjectrequired
  The unit of measure of the item.
  
  Show 3 properties
  group_idstringrequired
  maxLength: 100
  The group of the unit of measure.
  
  Example: "weight"
  unit_idstringrequired
  maxLength: 100
  The specific unit of measure within the group.
  
  Example: "weight.kilogram"
  unit_rationumberrequired
  format: double
  The ratio of the specified unit to the base unit of the group.
  
  Example: 1.24412
  priceobjectrequired
  Pricing for a single line, valid for every item type.
  
  Merges the standard amounts (with tax breakdown) and the final amounts (after discounts/modifiers).
  
  Totals and tax amounts can be negative for return-like operations (for example a deposit with operation_type = RETURN).
  
  Show 8 properties
  unit_amountintegerrequired
  format: int64minimum: 0
  The price of a single unit. If the tax_mode is GROSS it includes taxes, otherwise no tax is included. It does NOT include discounts.
  
  Example: 300
  total_net_amountobjectrequired
  The net amount (including modifiers if applied). It does NOT include discounts.
  
  Example: 252
  Show 2 properties
  currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
  valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
  total_gross_amountobjectrequired
  The gross amount (including modifiers if applied). It does NOT include discounts.
  
  Example: 300
  Show 2 properties
  currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
  valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
  taxesarray<object>required
  Taxes applied on top of the net amount resulting in the gross amount.
  
  Example: [{"id":"tax-vat-19","net_amount":252,"gross_amount":300,"tax_amount":48}]
  Show 6 properties
  idstringrequired
  maxLength: 100
  Tax ID from the Tax Service (External Id)
  
  Example: "b064ed44-66e1-45a1-a963-b783808f0436"
  net_amountobjectrequired
  Net amount before applying the tax. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Show 2 properties
  currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
  valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
  gross_amountobjectrequired
  Gross amount after applying the tax. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Show 2 properties
  currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
  valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
  tax_amountobjectrequired
  Amount of tax. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Show 2 properties
  currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
  valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
  namestring
  maxLength: 255
  Tax name, e.g. "MwSt."
  
  percentageinteger
  format: int64minimum: 0
  The tax rate percentage in minor units (1/100000). For example 19000 = 19%.
  
  Example: 19000
  total_net_amount_finalobjectrequired
  The final net amount including discounts and modifiers. Equals total_net_amount if no discounts apply.
  
  Example: 210
  Show 2 properties
  currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
  valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
  total_gross_amount_finalobjectrequired
  The final gross amount including discounts, modifiers and taxes. Equals total_gross_amount if no discounts apply.
  
  Example: 250
  Show 2 properties
  currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
  valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
  taxes_finalarray<object>required
  Taxes applied on top of total_net_amount_final resulting in total_gross_amount_final. Equals taxes if no discounts apply.
  
  Example: [{"id":"tax-vat-19","net_amount":210,"gross_amount":250,"tax_amount":40}]
  Show 6 properties
  idstringrequired
  maxLength: 100
  Tax ID from the Tax Service (External Id)
  
  Example: "b064ed44-66e1-45a1-a963-b783808f0436"
  net_amountobjectrequired
  Net amount before applying the tax. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Show 2 properties
  currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
  valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
  gross_amountobjectrequired
  Gross amount after applying the tax. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Show 2 properties
  currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
  valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
  tax_amountobjectrequired
  Amount of tax. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Show 2 properties
  currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
  valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
  namestring
  maxLength: 255
  Tax name, e.g. "MwSt."
  
  percentageinteger
  format: int64minimum: 0
  The tax rate percentage in minor units (1/100000). For example 19000 = 19%.
  
  Example: 19000
  discountsarray<object>
  Discounts applied. Discount amounts do not affect total_net_amount / total_gross_amount; they are reflected in the *_final amounts.
  
  Example: []
  Show 8 properties
  levelstringrequired
  minLength: 4maxLength: 4
  Specifies where discount was applied by user (either merchant or consumer):
  
  CART: Applied to the whole cart (calculated and distributed per sale item)
  
  ITEM: Applied to specific sale item
  
  Accepted values: ["ITEM", "CART"].
  
  Example: "CART"
  sourceobjectrequired
  The source of discount. Exactly one property must be set.
  
  Show 5 properties
  ad_hocobject
  Discount created ad-hoc on device during checkout.
  
  basicobject
  Preset discount applied manually on the POS.
  
  couponobject
  Discount applied manually when entering a coupon code at checkout.
  
  offerobject
  Discount applied automatically when cart is updated based on preset promotions.
  
  loyaltyobject
  Discount applied when redeeming a reward from the merchant's loyalty scheme.
  
  valueobjectrequired
  The value type of the discount, either a percentage based or absolute monetary value.
  
  It is required that only one of the following is set:
  
  absolute
  
  percentage.
  
  Show 2 properties
  absoluteinteger
  format: int64minimum: 0
  The absolute value in minor units of the currency according to the Sale.currency.scale. Example: 10000 = 10.00
  
  Example: 100
  percentageinteger
  format: int64minimum: 0
  The percentage in minor units (1/100000).
  
  Examples:
  
  10% -> 0.10 (decimal) = 10000 (minor units)
  
  15.5% -> 0.155 (decimal) = 15500 (minor units)
  
  0.001% -> 0.00001 (decimal) = 1 (minor units)
  
  Example: 10000
  net_amountintegerrequired
  format: int64minimum: 0
  The net amount of the discount. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Example: 100
  gross_amountintegerrequired
  format: int64minimum: 0
  The gross amount of the discount. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Example: 100
  tax_amountintegerrequired
  format: int64minimum: 0
  The tax amount of the discount. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Example: 100
  idstring
  maxLength: 100
  An id used to associate a discount line with a specific discount. Since we can apply multiple discounts (e.g. 2x 10% whole cart off) we need to be able to identify which discount line belongs to which cart discount. Recommended to use UUID identifiers.
  
  Example: "075b0b5c-a1f4-46da-9aca-92fb6dd5905d"
  descriptionstring
  maxLength: 250
  A description or reason of the discount.
  
  Example: "Happy Hour"
  service_typestring
  Options:"IN_HOUSE""TAKE_AWAY"
  The type of service for this line.
  
  Example: "IN_HOUSE"
  notestring
  maxLength: 300
  Optional free-text note attached to the line, visible on receipts.
  
  Example: "extra hot"
  categoriesarray<object>
  Categories the line belongs to. A shared optional structure available to any line; not a per-type field.
  
  Example: [{"id":"cat-hot-drinks","name":"Hot Drinks"}]
  Show 2 properties
  idstringrequired
  maxLength: 100
  The category id. Usually a UUID, but not always (legacy cases).
  
  Example: "b064ed44-66e1-45a1-a963-b783808f0436"
  namestringrequired
  maxLength: 30
  The category name.
  
  Example: "Food"
  modifiersarray<object>
  Modifiers customise a line (e.g. "oat milk" on a cappuccino). A shared optional structure available to any line; not a per-type field.
  
  Example: []
  Show 12 properties
  unit_amountintegerrequired
  format: int64minimum: 0
  The price of a single unit. If the tax_mode is GROSS, it includes taxes, otherwise no tax included. It doesn't include discounts.
  
  Example: 100
  total_net_amountintegerrequired
  format: int64minimum: 0
  The value of the amount in minor units of the currency according to the Sale.currency.scale. value can get large for some currencies and applications. Use Long type or a similar data type when parsing value.
  
  Example: 100
  total_gross_amountintegerrequired
  format: int64minimum: 0
  The value of the amount in minor units of the currency according to the Sale.currency.scale. value can get large for some currencies and applications. Use Long type or a similar data type when parsing value.
  
  Example: 100
  taxesarray<unknown>required
  Taxes applied on top of net amount resulting in gross amount.
  
  Show 6 properties
  idstringrequired
  maxLength: 100
  Tax ID from the Tax Service (External Id)
  
  Example: "b064ed44-66e1-45a1-a963-b783808f0436"
  net_amountintegerrequired
  format: int64minimum: 0
  Net amount before applying the tax. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Example: 100
  gross_amountintegerrequired
  format: int64minimum: 0
  Gross amount after applying the tax. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Example: 100
  tax_amountintegerrequired
  format: int64minimum: 0
  Amount of tax. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Example: 100
  namestring
  maxLength: 255
  Tax name, e.g. "MwSt."
  
  percentageinteger
  format: int64minimum: 0
  The tax rate percentage in minor units (1/100000). For example 19000 = 19%.
  
  Example: 19000
  total_net_amount_finalintegerrequired
  format: int64minimum: 0
  The final net amount includes discounts and modifiers. It does NOT include taxes. If no discounts are applied, it should be equal to total_net_amount.
  
  Example: 100
  total_gross_amount_finalintegerrequired
  format: int64minimum: 0
  The final gross amount includes discounts, modifiers, and taxes. If no discounts are applied, it should be equal to total_gross_amount.
  
  Example: 100
  taxes_finalarray<unknown>required
  Taxes applied on top of total_net_amount_final amount resulting in total_gross_amount_final amount. If no discounts are applied, it should be equal to taxes.
  
  Show 6 properties
  idstringrequired
  maxLength: 100
  Tax ID from the Tax Service (External Id)
  
  Example: "b064ed44-66e1-45a1-a963-b783808f0436"
  net_amountintegerrequired
  format: int64minimum: 0
  Net amount before applying the tax. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Example: 100
  gross_amountintegerrequired
  format: int64minimum: 0
  Gross amount after applying the tax. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Example: 100
  tax_amountintegerrequired
  format: int64minimum: 0
  Amount of tax. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Example: 100
  namestring
  maxLength: 255
  Tax name, e.g. "MwSt."
  
  percentageinteger
  format: int64minimum: 0
  The tax rate percentage in minor units (1/100000). For example 19000 = 19%.
  
  Example: 19000
  idstringrequired
  maxLength: 100
  Modifier id, coming from the Item Catalog
  
  Example: "b064ed44-66e1-45a1-a963-b783808f0436"
  namestringrequired
  maxLength: 150
  Modifier name, coming from the Item Catalog
  
  Example: "Extra Cheese"
  setobjectrequired
  Modifier set attached to an item.
  
  Show 2 properties
  idstringrequired
  maxLength: 100
  The id of the modifier set that modifier belongs to.
  
  Example: "b064ed44-66e1-45a1-a963-b783808f0436"
  namestringrequired
  minLength: 1maxLength: 150
  The name of the modifier set that the modifier belongs to.
  
  Example: "Burger Toppings"
  quantitynumberrequired
  format: doubleminimum: 0
  The numerical value representing the quantity in the specified unit.
  
  Example: 2.15332
  discountsarray<object>
  Discounts applied.
  
  Important: Discount amounts shouldn't take effect on net and gross amounts.
  
  Discount money amounts depend on where discount was applied:
  
  for item level discount: whole discount money amount is applied
  
  for cart level discount: only part of the whole amount is applied (discount money value is split on each line item)
  
  Show 8 properties
  levelstringrequired
  minLength: 4maxLength: 4
  Specifies where discount was applied by user (either merchant or consumer):
  
  CART: Applied to the whole cart (calculated and distributed per sale item)
  
  ITEM: Applied to specific sale item
  
  Accepted values: ["ITEM", "CART"].
  
  Example: "CART"
  sourceobjectrequired
  The source of discount. Exactly one property must be set.
  
  Show 5 properties
  ad_hocobject
  Discount created ad-hoc on device during checkout.
  
  basicobject
  Preset discount applied manually on the POS.
  
  couponobject
  Discount applied manually when entering a coupon code at checkout.
  
  offerobject
  Discount applied automatically when cart is updated based on preset promotions.
  
  loyaltyobject
  Discount applied when redeeming a reward from the merchant's loyalty scheme.
  
  valueobjectrequired
  The value type of the discount, either a percentage based or absolute monetary value.
  
  It is required that only one of the following is set:
  
  absolute
  
  percentage.
  
  Show 2 properties
  absoluteinteger
  format: int64minimum: 0
  The absolute value in minor units of the currency according to the Sale.currency.scale. Example: 10000 = 10.00
  
  Example: 100
  percentageinteger
  format: int64minimum: 0
  The percentage in minor units (1/100000).
  
  Examples:
  
  10% -> 0.10 (decimal) = 10000 (minor units)
  
  15.5% -> 0.155 (decimal) = 15500 (minor units)
  
  0.001% -> 0.00001 (decimal) = 1 (minor units)
  
  Example: 10000
  net_amountintegerrequired
  format: int64minimum: 0
  The net amount of the discount. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Example: 100
  gross_amountintegerrequired
  format: int64minimum: 0
  The gross amount of the discount. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Example: 100
  tax_amountintegerrequired
  format: int64minimum: 0
  The tax amount of the discount. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Example: 100
  idstring
  maxLength: 100
  An id used to associate a discount line with a specific discount. Since we can apply multiple discounts (e.g. 2x 10% whole cart off) we need to be able to identify which discount line belongs to which cart discount. Recommended to use UUID identifiers.
  
  Example: "075b0b5c-a1f4-46da-9aca-92fb6dd5905d"
  descriptionstring
  maxLength: 250
  A description or reason of the discount.
  
  Example: "Happy Hour"
  referencesobject
  Outward identifiers and links for a line, kept in one place rather than scattered per item type.
  
  Show 4 properties
  catalog_sourcestring
  Options:"SUMUP""EXTERNAL"
  default: "SUMUP"
  The source of the catalog the line originates from.
  
  Example: "SUMUP"
  catalog_referencestring
  maxLength: 255
  Reference to the backing catalog entity (item variant, deposit, ...), typically a URN such as urn:sumup:pos:variant:${MERCHANT_CODE}:${ITEM_ID}:${VARIANT_ID} or urn:sumup:pos:deposit:${MERCHANT_CODE}:${DEPOSIT_ID}. Empty for ad-hoc / manual lines. Type-agnostic on purpose: a new item type backed by a catalog entity reuses this field instead of adding its own.
  
  Example: "urn:sumup:pos:variant:MCGLE7VC:9736e947-6f1f-487f-846a-c5954fb06a5a:7fff192f-ce29-4673-890f-2d68ba557946"
  external_idstring
  maxLength: 250
  An external reference id connecting this line to another system.
  
  Example: "POS-LINE-001"
  skustring
  maxLength: 100
  Stock keeping unit, enriched from the Catalog when available.
  
  Example: "COFFEE-LARGE"
  featuresarray<object>
  Named, typed, type-specific data. New item types add their data here as features instead of new schema variants. See Feature for per-type examples.
  
  Example: [{"name":"variant_name","value_type":"TEXT","value":"Large"}]
  Show 3 properties
  namestringrequired
  maxLength: 100
  The feature name/key.
  
  Example: "operation_type"
  value_typestringrequired
  Options:"TEXT""INTEGER""DECIMAL""DATE""BOOLEAN"
  The data type of a feature value. The wire value is always a string and is parsed according to this type.
  
  Example: "TEXT"
  valuestringrequired
  maxLength: 1000
  The feature value in canonical string form, to be parsed per value_type (e.g. INTEGER -> "3", DECIMAL -> "1.50", DATE -> "2026-07-02", BOOLEAN -> "true"). Carrying it as a string keeps the wire format stable as new feature names and value types are introduced.
  
  Example: "SALE"
- priceobjectrequired
  Sale-level pricing aggregate, parallel to LineItemPrice on each SaleLineItem.
  
  Line-level breakdown (unit price, line discounts, per-line taxes) lives on items[].price. This object holds the rolled-up totals and cart-level adjustments that consumers use for receipts and payment reconciliation.
  
  Show 4 properties
  net_amountobjectrequired
  Final net total for the sale: sum of items[].price.total_net_amount_final after cart-level discounts (tips excluded). In minor units according to Sale.currency.scale.
  
  Example: 777
  Show 2 properties
  currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
  valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
  gross_amountobjectrequired
  Final gross total for the sale: sum of items[].price.total_gross_amount_final after cart-level discounts (tips excluded). Same value as search total_amount, in minor units according to Sale.currency.scale. Payment amounts include tips and can therefore differ from this gross total.
  
  Example: 925
  Show 2 properties
  currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
  valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
  taxesarray<object>required
  Tax lines aggregated across the sale (after cart-level discounts). Per-line tax detail remains on items[].price.taxes / taxes_final.
  
  Example: [{"id":"tax-vat-19","net_amount":777,"gross_amount":925,"tax_amount":148}]
  Show 6 properties
  idstringrequired
  maxLength: 100
  Tax ID from the Tax Service (External Id)
  
  Example: "b064ed44-66e1-45a1-a963-b783808f0436"
  net_amountobjectrequired
  Net amount before applying the tax. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Show 2 properties
  currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
  valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
  gross_amountobjectrequired
  Gross amount after applying the tax. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Show 2 properties
  currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
  valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
  tax_amountobjectrequired
  Amount of tax. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Show 2 properties
  currencystringrequired
  Currency ISO 4217 code
  
  Example: "MXN"
  valueintegerrequired
  Amount in minor units (e.g. cents).
  
  Example: 1000
  namestring
  maxLength: 255
  Tax name, e.g. "MwSt."
  
  percentageinteger
  format: int64minimum: 0
  The tax rate percentage in minor units (1/100000). For example 19000 = 19%.
  
  Example: 19000
  cart_discountsarray<object>
  Discounts applied at cart level. Item-level discounts remain on items[].price.discounts.
  
  Example: []
  Show 8 properties
  levelstringrequired
  minLength: 4maxLength: 4
  Specifies where discount was applied by user (either merchant or consumer):
  
  CART: Applied to the whole cart (calculated and distributed per sale item)
  
  ITEM: Applied to specific sale item
  
  Accepted values: ["ITEM", "CART"].
  
  Example: "CART"
  sourceobjectrequired
  The source of discount. Exactly one property must be set.
  
  Show 5 properties
  ad_hocobject
  Discount created ad-hoc on device during checkout.
  
  Show 3 properties
  idstring
  format: uuid
  The unique identifier of the ad-hoc discount.
  
  Example: "075b0b5c-a1f4-46da-9aca-92fb6dd5905d"
  namestring
  maxLength: 100
  The name of the ad-hoc discount.
  
  Example: "Happy Hour"
  descriptionstring
  maxLength: 250
  The description of the ad-hoc discount.
  
  Example: "Happy Hour from 10 to 12."
  basicobject
  Preset discount applied manually on the POS.
  
  Show 4 properties
  idstringrequired
  format: uuid
  The unique identifier of the basic discount.
  
  Example: "075b0b5c-a1f4-46da-9aca-92fb6dd5905d"
  namestringrequired
  maxLength: 100
  The name of the basic discount.
  
  Example: "Staff discount"
  application_modestringrequired
  Options:"MANUAL""AUTOMATIC"
  Method of applying the discount to the items or cart.
  
  Example: "MANUAL"
  descriptionstringnullable
  maxLength: 250
  The description of the loyalty discount.
  
  Example: "10% off food for staff members."
  couponobject
  Discount applied manually when entering a coupon code at checkout.
  
  Show 6 properties
  idstringrequired
  format: uuid
  The unique identifier of the coupon discount.
  
  Example: "075b0b5c-a1f4-46da-9aca-92fb6dd5905d"
  codestringrequired
  maxLength: 100
  The coupon code.
  
  Example: "FREE_COFFEE"
  namestringrequired
  maxLength: 100
  The name of the coupon discount.
  
  Example: "Free coffee"
  application_modestringrequired
  Options:"MANUAL""AUTOMATIC"
  Method of applying the discount to the items or cart.
  
  Example: "MANUAL"
  descriptionstringnullable
  maxLength: 250
  The description of the coupon discount.
  
  Example: "Free coffee with this coupon."
  discount_classstringnullable
  Options:"ITEM""CATEGORY""BUNDLE""BUY_X_GET_Y""MEAL_DEAL"
  The method used to target items to discount. Must be populated for ITEM level discounts, and must be null for CART level discounts (CART level targets all items, therefore none of these categories apply).
  
  Example: "ITEM"
  offerobject
  Discount applied automatically when cart is updated based on preset promotions.
  
  Show 5 properties
  idstringrequired
  format: uuid
  The unique identifier of the offer discount.
  
  Example: "075b0b5c-a1f4-46da-9aca-92fb6dd5905d"
  namestringrequired
  maxLength: 100
  The name of the offer discount.
  
  Example: "Breakfast combo deal"
  application_modestringrequired
  Options:"MANUAL""AUTOMATIC"
  Method of applying the discount to the items or cart.
  
  Example: "MANUAL"
  descriptionstringnullable
  maxLength: 250
  The description of the offer discount.
  
  Example: "Buy a Croissant, get a coffee for £1"
  discount_classstringnullable
  Options:"ITEM""CATEGORY""BUNDLE""BUY_X_GET_Y""MEAL_DEAL"
  The method used to target items to discount. Must be populated for ITEM level discounts, and must be null for CART level discounts (CART level targets all items, therefore none of these categories apply).
  
  Example: "ITEM"
  loyaltyobject
  Discount applied when redeeming a reward from the merchant's loyalty scheme.
  
  Show 8 properties
  idstringrequired
  format: uuid
  The unique identifier of the promotion or reward.
  
  Example: "075b0b5c-a1f4-46da-9aca-92fb6dd5905d"
  loyalty_typestringrequired
  Options:"PROMOTION""REWARD"
  The type of loyalty discount, either a promotion (e.g. new customer discount) or a reward (free coffee after completing stamp card).
  
  Example: "REWARD"
  scheme_typestringrequired
  Options:"STAMPS""POINTS"
  The scheme type of the loyalty program.
  
  Example: "POINTS"
  namestringrequired
  maxLength: 100
  The name of the loyalty discount.
  
  Example: "Free coffee"
  application_modestringrequired
  Options:"MANUAL""AUTOMATIC"
  Method of applying the discount to the items or cart.
  
  Example: "MANUAL"
  pointsintegernullable
  format: int64minimum: 1
  The number of points used for this loyalty discount. Must be a positive integer if the scheme type is POINTS. Must not be populated if the scheme type is STAMPS.
  
  Example: 50
  descriptionstringnullable
  maxLength: 250
  The description of the loyalty discount.
  
  Example: "Free coffee for 50 points"
  discount_classstringnullable
  Options:"ITEM""CATEGORY""BUNDLE""BUY_X_GET_Y""MEAL_DEAL"
  The method used to target items to discount. Must be populated for ITEM level discounts, and must be null for CART level discounts (CART level targets all items, therefore none of these categories apply).
  
  Example: "ITEM"
  valueobjectrequired
  The value type of the discount, either a percentage based or absolute monetary value.
  
  It is required that only one of the following is set:
  
  absolute
  
  percentage.
  
  Show 2 properties
  absoluteinteger
  format: int64minimum: 0
  The absolute value in minor units of the currency according to the Sale.currency.scale. Example: 10000 = 10.00
  
  Example: 100
  percentageinteger
  format: int64minimum: 0
  The percentage in minor units (1/100000).
  
  Examples:
  
  10% -> 0.10 (decimal) = 10000 (minor units)
  
  15.5% -> 0.155 (decimal) = 15500 (minor units)
  
  0.001% -> 0.00001 (decimal) = 1 (minor units)
  
  Example: 10000
  net_amountintegerrequired
  format: int64minimum: 0
  The net amount of the discount. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Example: 100
  gross_amountintegerrequired
  format: int64minimum: 0
  The gross amount of the discount. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Example: 100
  tax_amountintegerrequired
  format: int64minimum: 0
  The tax amount of the discount. The value of the amount in minor units of the currency according to the Sale.currency.scale.
  
  Example: 100
  idstring
  maxLength: 100
  An id used to associate a discount line with a specific discount. Since we can apply multiple discounts (e.g. 2x 10% whole cart off) we need to be able to identify which discount line belongs to which cart discount. Recommended to use UUID identifiers.
  
  Example: "075b0b5c-a1f4-46da-9aca-92fb6dd5905d"
  descriptionstring
  maxLength: 250
  A description or reason of the discount.
  
  Example: "Happy Hour"
- tax_modestringrequired
  Options:"NO_TAX""GROSS""NET"
  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.
  
  Example: "NO_TAX"
- sourceobjectrequired
  Information about the source of the sale.
  
  Show 4 properties
  channelstringrequired
  The sale_channel is field that indicates the channel through which the sale was made. For example, if the sale was made in the merchant app, the sale_channel could be POS. If the sale was made on a kiosk, the sale_channel is KIOSK.
  
  Accepted values: ["POS", "KIOSK", "ONLINE_STORE", "SOLO", "ORDER_AND_PAY", "INVOICE", "BOOKINGS", "ORDER_AGGREGATOR", "SUBSCRIPTIONS", "UNKNOWN"].
  
  Example: "POS"
  sub_channelstring
  maxLength: 50
  The sub_channel is an optional field that can be used to provide more information about the sale_channel. For example, if the sale_channel is ONLINE_PAYMENTS, the sub_channel could be "WIX" or "QR_CODE" or "WOOCOMMERCE".
  
  Example: "QR_CODE"
  external_idstring
  maxLength: 250
  An external reference ID for connecting orders/sales between products
  
  Example: "123456"
  external_sub_channel_idstring
  maxLength: 250
  An external reference ID for the sub-channel. For example, when channel is BOOKINGS and sub_channel is POS, this can hold the OMS order ID while external_id holds the appointment ID.
  
  Example: "9736e947-6f1f-487f-846a-c5954fb06a5a"
- paymentsarray<object>required
  Payments on this sale, in the order they were recorded.
  
  Example: [{"method":"card","reference":"TERTYFQ4G3","type":"purchase","amount":975,"status":"SUCCESSFUL","processed_at":"2026-06-02T10:20:00Z"}]
  Show 9 properties
  methodstringrequired
  maxLength: 20
  Payment method on public sales read API v1.0. Digital wallets are first-class methods. Gift card payments use gift_card, not apm. Input is case-insensitive; the canonical form is lowercase snake_case. VALUES: [card, cash, apm, external, apple_pay, google_pay, whatsapp_pay, gift_card].
  
  Example: "card"
  referencestringrequired
  maxLength: 50
  The reference to the actual payment used for this sale, e.g. the sumup transaction code.
  
  Example: "TERTYFQ4G3"
  typestringrequired
  default: "purchase"
  Payment operation type. This is distinct from the payment instrument in method. Input is case-insensitive; the canonical form is lowercase snake_case. VALUES: [purchase, unreferenced_refund] Defaults to "purchase" if unspecified. Either a normal purchase or an unreferenced refund for negative sales like deposit returns.
  
  Example: "purchase"
  amountintegerrequired
  format: int64minimum: 0
  The amount of the payment including tips. The value of the amount in minor units of Sale.currency.
  
  Example: 975
  statusstringrequired
  Options:"FAILED""SUCCESSFUL""CANCELED"
  The status of the payment.
  
  Example: "SUCCESSFUL"
  processed_atstringrequired
  format: date-time
  UTC date-time when SumUp recorded this payment’s exposed status (successful, failed, or canceled). Server processed time when available; otherwise the payment provider’s transaction time. Not the device clock.
  
  Example: "2017-07-21T17:32:28+01:00"
  apm_typestring
  maxLength: 20
  Alternative payment method type when method is apm. Gift card is not an APM on this API. Input is case-insensitive; the canonical form is lowercase snake_case. VALUES: [qr_code_pix, sepa_dd, paypal, sumup_pay, twint, iris].
  
  cardobject
  Card brand, credit/debit processing type, and last four digits.
  
  Show 3 properties
  brandstringrequired
  maxLength: 20
  The brand of the card. Input is case-insensitive; the canonical form is lowercase snake_case. VALUES: [amex, cup, diners, discover, elo, elv, hipercard, jcb, maestro, mastercard, visa, visa_electron, visa_vpay, vr, eftpos, conecs, swile, girocard, interac, sumup, bancomat].
  
  Example: "visa"
  typestringrequired
  Options:"credit""debit""unknown"
  Credit or debit processing choice, not brand or funding. unknown when unavailable; prepaid/voucher are not processing types.
  
  Example: "debit"
  last_4_digitsstringrequired
  minLength: 4maxLength: 4pattern: ^\d{4}$
  The last 4 digits of the card used for the payment.
  
  Example: "1234"
  gift_cardobject
  Gift card used for this payment. Present when method is gift_card and the gift card id is known. Gift card IDs use the format "GC" followed by 9 alphanumeric characters (e.g. GCZ3NTMB1V).
  
  Show 1 property
  idstringrequired
  Gift card identifier. Format "GC" followed by 9 alphanumeric characters (e.g. GCZ3NTMB1V).
  
  Example: "GCZ3NTMB1V"
- created_atstringrequired
  format: date-time
  Instant when the sale was created.
  
  Example: "2026-06-02T10:15:00Z"
- closed_atstringrequired
  format: date-time
  Instant when the sale was closed. Always present: non-finalised sales are never returned.
  
  Example: "2026-06-02T10:20:00Z"
- statestringrequired
  Options:"CLOSED"
  Lifecycle state of the sale. Non-finalised sales are never returned; only fully-paid sales.
  
  Example: "CLOSED"
- 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
  maxLength: 160
  Human-readable name of the sale (not unique, not the sale id).
  
  Example: "Order 1234"
- notestring
  maxLength: 300
  Optional note attached to the sale, visible on receipts and the UI.
  
  Example: "Please deliver to the back door."
pagination_tokenstring
Pagination token for subsequent requests. Should only be set by clients if they have received a token in the previous response, and this request is an immediate follow-up request to that response to load the subsequent page. Clients should treat this as an opaque token and should not attempt to parse it in any way.

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.

GET

Code sample

curl --request GET \
  --url https://api.sumup.com/v1.0/merchants/MCZM9TGQ/sales \
  --header 'Authorization: Bearer <token>'

import SumUp from "@sumup/sdk";

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

  const result = await client.sales.listSalesV10(
    "MCZM9TGQ",
    {
      "pagination_token": "66bcbtzelrubzeuzruzgu76678trncH"
    }
  );
  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.ListSalesV10Async(
            "your-merchant-code",
            new SalesListSalesV10Options
            {
                PaginationToken = "example",
                PaginationLimit = 10,
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

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

    var result = client.sales().listSalesV10(
            "MCZM9TGQ"
        );
    System.out.println(result);
  }
}

import os

import sumup

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

$queryParams = new \SumUp\Services\SalesListSalesV10Params();
$queryParams->paginationToken = '66bcbtzelrubzeuzruzgu76678trncH';
$queryParams->paginationLimit = 10;

$result = $sumup->sales()->listSalesV10(
    'MCZM9TGQ',
    $queryParams,
);

var_dump($result);

package main

import (
	"context"
	"fmt"

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

func main() {
	client := sumup.NewClient()
	result, err := client.Sales.ListSalesV10(context.TODO(), "MCZM9TGQ", sumup.SalesListSalesV10Params{
		PaginationToken: new("66bcbtzelrubzeuzruzgu76678trncH"),
		PaginationLimit: new(10),
	})
	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 response = client
        .sales()
        .list_sales_v10(
            "MERCHANT_CODE",
            sumup::resources::sales::ListSalesV10Params::builder().build(),
        )
        .await
        .expect("list_sales_v10 request failed");
    println!("{response:#?}");
}

Response example

{
  "items": [
    {
      "id": "dbe3178d-4b83-5024-9b26-9b8e1b280514",
      "user_id": "d6f51684-519b-454c-bdb3-deeb05f52b92",
      "currency": "EUR",
      "name": "Order 1234",
      "note": "Please deliver to the back door.",
      "items": [
        {
          "id": "line-1",
          "type": "CATALOG",
          "name": "Cappuccino",
          "quantity": 2.15332,
          "unit_of_measure": {
            "group_id": "weight",
            "unit_id": "weight.kilogram",
            "unit_ratio": 1.24412
          },
          "service_type": "IN_HOUSE",
          "note": "extra hot",
          "price": {
            "unit_amount": 300,
            "total_net_amount": 252,
            "total_gross_amount": 300,
            "taxes": [
              {
                "id": "tax-vat-19",
                "net_amount": 252,
                "gross_amount": 300,
                "tax_amount": 48
              }
            ],
            "discounts": [],
            "total_net_amount_final": 210,
            "total_gross_amount_final": 250,
            "taxes_final": [
              {
                "id": "tax-vat-19",
                "net_amount": 210,
                "gross_amount": 250,
                "tax_amount": 40
              }
            ]
          },
          "categories": [
            {
              "id": "cat-hot-drinks",
              "name": "Hot Drinks"
            }
          ],
          "modifiers": [],
          "references": {
            "catalog_source": "SUMUP",
            "catalog_reference": "urn:sumup:pos:variant:MCGLE7VC:9736e947-6f1f-487f-846a-c5954fb06a5a:7fff192f-ce29-4673-890f-2d68ba557946",
            "external_id": "POS-LINE-001",
            "sku": "COFFEE-LARGE"
          },
          "features": [
            {
              "name": "variant_name",
              "value_type": "TEXT",
              "value": "Large"
            }
          ]
        }
      ],
      "price": {
        "net_amount": 777,
        "gross_amount": 925,
        "cart_discounts": [],
        "taxes": [
          {
            "id": "tax-vat-19",
            "net_amount": 777,
            "gross_amount": 925,
            "tax_amount": 148
          }
        ]
      },
      "tax_mode": "NO_TAX",
      "source": {
        "channel": "POS",
        "sub_channel": "QR_CODE",
        "external_id": "123456",
        "external_sub_channel_id": "9736e947-6f1f-487f-846a-c5954fb06a5a"
      },
      "payments": [
        {
          "method": "card",
          "reference": "TERTYFQ4G3",
          "type": "purchase",
          "amount": 975,
          "status": "SUCCESSFUL",
          "processed_at": "2026-06-02T10:20:00Z"
        }
      ],
      "created_at": "2026-06-02T10:15:00Z",
      "closed_at": "2026-06-02T10:20:00Z",
      "state": "CLOSED"
    }
  ],
  "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"
}