Orders

POS orders capture physical sales from card readers, cash registers, and self-checkout kiosks. Each order has one or more line items and is linked to a product in your catalogue.

List orders

bash

GET /v1/slate/orders

Name	Type	Required	Description
filter[payment_method]	string	No	Filter by card or cash.
filter[source]	string	No	Filter by terminal \| register \| self_checkout.
filter[shift_id]	string	No	Filter orders belonging to a specific shift.
filter[created_after]	string	No	ISO 8601 datetime lower bound.
filter[created_before]	string	No	ISO 8601 datetime upper bound.
page	integer	No	Page number. Defaults to 1.
per_page	integer	No	Results per page. Max 100.

Get an order

bash

GET /v1/slate/orders/:id

json

{
  "data": {
    "id": "f3a2b1c0-...",
    "tenant_id": "ten_01hxyz",
    "order_number": "ORD-1717200000000",
    "total": 27.50,
    "tax_amount": 2.50,
    "payment_method": "card",
    "card_last_four": "4242",
    "auth_code": "A1B2C3",
    "cashier_id": "usr_01hxyz",
    "source": "terminal",
    "created_at": "2025-06-01T08:30:00Z",
    "lines": [
      {
        "id": "...",
        "product_id": "...",
        "product_name": "Flat White",
        "price": 5.50,
        "qty": 2
      }
    ]
  }
}

Create an order

bash

POST /v1/slate/orders

Name	Type	Required	Description
lines	array	Yes	Array of line items. Each must have product_name, price, qty. product_id optional.
payment_method	string	Yes	card or cash.
tax_rate	number	No	Tax percentage applied to subtotal (e.g. 10 for 10% GST). Defaults to 0.
source	string	No	terminal \| register \| self_checkout. Defaults to register.
card_last_four	string	No	Last 4 digits of the card used (for card payments).
auth_code	string	No	Terminal authorisation code returned by the card reader.

bash

curl -X POST https://api.hldgroup.org/v1/slate/orders \
  -H "x-internal-secret: <key>" \
  -H "x-user-id: usr_01hxyz" \
  -H "x-tenant-id: ten_01hxyz" \
  -H "x-platform-role: tenant-system-admin" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "card",
    "card_last_four": "4242",
    "auth_code": "A1B2C3",
    "tax_rate": 10,
    "source": "terminal",
    "lines": [
      { "product_name": "Flat White", "price": 5.50, "qty": 2, "product_id": "prod_01hxyz" },
      { "product_name": "Banana Bread", "price": 7.00, "qty": 1 }
    ]
  }'

Note:Total and tax are calculated server-side from the line items and tax_rate. The total field in the response is the source of truth — do not display a pre-calculated total before the response arrives.

Products Shifts