Skip to content

Get a sale

Open in ClaudeOpen in ChatGPTView as Markdown
GET
/sales/{id}

Returns one sale in any non-open status, with its line items, payments and totals. A parked (open) sale reads as not found.

  • 404 NOT_FOUND: the id is foreign, unknown, or names a parked sale.

Requires scope: sales:read

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

Get a sale

Media typeapplication/json
object
data
required
object
adjustments
required
Array<object>
object
amount
required

Signed: positive for a surcharge, negative for a cash discount. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
label
required
string
tax_amount
required

The tax charged on this adjustment. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
tax_id
required
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
taxable
required
boolean
type
required
string
Allowed values: surcharge cash_discount rounding
cash_discount_total
required

Total cash-discount adjustment. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
completed_at
required
Any of:
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/
created_at
required
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/
customer_id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
discount_total
required

Reporting total: line + order + promo discount. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
discounts
required
Array<object>
object
allocation_method
required
string
Allowed values: across each
code
required
string | null
id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
promotion_id
required
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
source
required
string
Allowed values: manual_line manual_order promo coupon
target_line_id
required
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
target_type
required
string
Allowed values: line_item entire_sale
title
required
string | null
value
required

Cents when value_type is fixed; basis points when percent.

integer
>= -9007199254740991 <= 9007199254740991
value_type
required
string
Allowed values: percent fixed
id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
line_count
required
integer
>= -9007199254740991 <= 9007199254740991
line_discount_total
required

The line-level part of discount_total. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
lines
required
Array<object>
object
discount_allocations
required
Array<object>
object
amount
required

The amount of this line allocated to the discount. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
discount_id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
discount_total
required

The total discount allocated to this line. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
list_price
required
Any of:

The snapshot catalog price. Integer, 4 decimal places (1.2345 = 12345).

integer
>= -9007199254740991 <= 9007199254740991
note
required
string | null
price_book_id
required
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
price_total
required

The line total, net of the line discount. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
product_id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
product_name
required
string
quantity
required

Decimal, 3 places. Negative on a refund line.

number
refunded_qty
required

Decimal, 3 places. Cumulative quantity refunded against this line.

number
sku
required
string | null
source_sale_line_id
required
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
tax_id
required
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
tax_rate
required
Any of:

The snapshot tax rate. Integer basis points (1/100 of a percent).

integer
>= -9007199254740991 <= 9007199254740991
tax_total
required

The tax charged on this line. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
unit_discount
required

The per-unit discount. Integer, 4 decimal places (1.2345 = 12345).

integer
>= -9007199254740991 <= 9007199254740991
unit_price
required

The snapshot unit price. Integer, 4 decimal places (1.2345 = 12345).

integer
>= -9007199254740991 <= 9007199254740991
note
required
string | null
outlet_id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
paid_total
required

Total tendered. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
parent_sale_id
required
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
payments
required
Array<object>
object
amount
required

The tender amount. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
amount_tendered
required
Any of:

Cash only: the amount physically handed over. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
card_brand
required
string | null
created_at
required
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/
entry_mode
required
Any of:
string
Allowed values: chip contactless swipe manual tap_to_pay
gift_card_id
required
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
last4
required
string | null
payment_type_id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
refunded_amount
required

The cumulative amount refunded against this tender. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
status
required
string
Allowed values: pending processing authorized captured voided refunded partially_refunded failed cancelled
receipt_label
required
string | null
receipt_number
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
register_id
required
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
rounding_total
required

Total rounding adjustment. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
source
required
string
staff_id
required
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
status
required
string
Allowed values: open completed partially_refunded refunded voided
subtotal
required

Already net of the line discount. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
surcharge_total
required

Total surcharge adjustment. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
tax_total
required

Total tax charged. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
taxes
required
Array<object>
object
id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
name
required
string
rate
required

The snapshot tax rate. Integer basis points (1/100 of a percent).

integer
>= -9007199254740991 <= 9007199254740991
tax_amount
required

The tax charged at this rate. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
tax_id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
taxable_amount
required

The amount this rate was applied to. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
total
required

The sale total. Integer minor units (cents).

integer
>= -9007199254740991 <= 9007199254740991
total_qty
required

Decimal, 3 places. Sum of line quantities.

number
updated_at
required
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/
version
required

Opaque delta-sync version. Increases with every change; use it to detect updates.

string
voided_at
required
Any of:
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$/
Example
{
  "data": {
    "adjustments": [
      {
        "type": "surcharge"
      }
    ],
    "discounts": [
      {
        "allocation_method": "across",
        "source": "manual_line",
        "target_type": "line_item",
        "value_type": "percent"
      }
    ],
    "payments": [
      {
        "entry_mode": "chip",
        "status": "pending"
      }
    ],
    "status": "open"
  }
}

default

Section titled “default”

An error response.

Media typeapplication/json
object
error
required
object
code
required

A machine-readable error code, e.g. VALIDATION_FAILED.

string
Allowed values: UNAUTHORIZED PLAN_REQUIRED INSUFFICIENT_SCOPE NOT_FOUND VALIDATION_FAILED CONFLICT STALE_VERSION RATE_LIMITED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS IMAGE_FETCH_FAILED UNPROCESSABLE INTERNAL RETAILER_CANCELLED RETAILER_SUSPENDED RETAILER_NOT_FOUND TRIAL_DECISION_REQUIRED PLAN_USERS_EXCEEDED RETAILER_PAUSED PRODUCT_LIMIT_REACHED NOT_STOCK_TRACKED REASON_DIRECTION_MISMATCH REASON_NOT_ALLOWED INSUFFICIENT_STOCK OUTLET_DELETED
fields
Array<object>
object
field
required
string
message
required
string
message
required

A plain-English sentence describing what went wrong.

string
Example
{
  "error": {
    "code": "UNAUTHORIZED"
  }
}