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

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Results per page (default: 50, max: 100)
start_date	date	First day of the date range (YYYY-MM-DD), from the start of that day. Must be sent together with end_date.
end_date	date	Last 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.
period	string	Instead of dates: today, yesterday, week (last 7 days) or month (last month)
status	string	pending, ready, completed or voided
search	string	Sale ID, receipt number, or customer name / email / phone. When set, the date window is not applied.
fulfillment_method	string	Only sales with this fulfillment method
cash_drawer_session_id	integer	Only 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": { ... }
}

Field	Notes
subtotal, tax_amount, discount_amount, total, line unit_price / discount_amount / total	Two-decimal strings
payment_method	The sale's payment method. Individual split payments are not included.
clerk	Full name of the staff member on the sale
voided_at, void_reason	Present on voided sales
green_echeck_surcharge, green_echeck_total_paid	Present on Green eCheck sales: the surcharge and the total debited. The sale totals themselves exclude the surcharge.
line notes	Present when the line has a note
line modifiers	Each { "name", "quantity", "price_adjustment", "removed" }

Fields with no value are omitted rather than sent as null.

---

Get a Sale

GET /api/v1/sales/:id

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