Skip to main content
Sign in with your store to see only the help that applies to you.

Sales API

Required scope: sales:read

Sales are read-only via the Developer API. Any non-GET request (creating, completing or voiding a sale) returns 403 Forbidden.


List Sales​

GET /api/v1/sales

Returns a paginated list of sales, newest first (by creation time).

Defaults to today

With no date parameters, only today's sales are returned. A sale is matched on completed_at if it has one, otherwise on created_at.

Query Parameters​

ParameterTypeDescription
pageintegerPage number (default: 1)
per_pageintegerResults per page (default: 50, max: 100)
start_datedateFirst day of the date range (YYYY-MM-DD), from the start of that day. Must be sent together with end_date.
end_datedateLast day of the date range (YYYY-MM-DD), up to the end of that day — the day itself is included. Days are whole days in the store's timezone.
periodstringInstead of dates: today, yesterday, week (last 7 days) or month (last month)
statusstringpending, ready, completed or voided
searchstringSale ID, receipt number, customer name / email / phone, or the customer name typed on the sale. When set, the date window is not applied.
fulfillment_methodstringOnly sales with this fulfillment method
cash_drawer_session_idintegerOnly sales from this cash drawer session

status=pending behaves differently: the date window is not applied, and it also returns non-voided sales still awaiting local delivery or shipping, even if they are completed.

Response​

{
"data": [
{
"id": 456,
"receipt_number": "R-000456",
"status": "completed",
"source": "pos",
"sale_type": "retail",
"payment_method": "debit",
"subtotal": "42.50",
"tax_amount": "5.53",
"discount_amount": "0.00",
"total": "48.03",
"line_items": [
{
"id": 1001,
"product_id": 1,
"product_name": "Blue Dream 3.5g",
"sku": "BD-35",
"quantity": 1.0,
"unit_price": "35.00",
"discount_amount": "0.00",
"total": "35.00",
"kitchen_item": false,
"modifiers": []
}
],
"customer": {
"id": 1,
"name": "Jane Smith",
"customer_code": "C10001"
},
"clerk": "Mike Jones",
"completed_at": "2026-03-22T14:30:00Z",
"created_at": "2026-03-22T14:28:00Z",
"updated_at": "2026-03-22T14:30:00Z"
}
],
"pagination": { ... }
}
FieldNotes
subtotal, tax_amount, discount_amount, total, line unit_price / discount_amount / totalTwo-decimal strings
payment_methodThe sale's payment method. Individual split payments are not included.
clerkFull name of the staff member on the sale
voided_at, void_reasonPresent on voided sales
green_echeck_surcharge, green_echeck_total_paidPresent on Green eCheck sales: the surcharge and the total debited. The sale totals themselves exclude the surcharge.
line notesPresent when the line has a note
line modifiersEach { "name", "text_value", "quantity", "price_adjustment", "removed" }. price_adjustment is a number, not a string; text_value (what the customer typed, for a typed modifier) is null when empty.

On the sale and its line items, fields with no value are omitted rather than sent as null (modifier entries are not trimmed this way).


Get a Sale​

GET /api/v1/sales/:id

Returns a single sale in the same shape as the list.