Orders

An order is the container for a payment transaction. Create an order first, then initiate a payment against it.

Create an order

POST /pos/v1/orders

Required scopes: tilt/payments:create

Request body

{
  "location_id": "uuid",
  "total_cents": 5000,
  "description": "Fleet service — invoice #INV-001",
  "external_reference": "INV-001",
  "external_source": "my-dms",
  "external_id": "dms-order-9912",
  "customer_name": "Alice Example",
  "customer_phone": "+15551234567",
  "customer_email": "alice@example.com",
  "department_id": "uuid-optional",
  "metadata": {},
  "level3": { }
}

Field	Type	Required	Description
`location_id`	UUID	Yes	The location where this order originates. Must be within your partner scope.
`total_cents`	integer	Yes	Order total in cents. Must be > 0.
`description`	string	No	Free-text description shown in the admin portal and on receipts.
`external_reference`	string	No	Your internal reference (invoice #, PO #). Indexed — searchable in the portal.
`external_source`	string	No	Source system name (e.g. `"my-dms"`).
`external_id`	string	No	Source system’s primary key for this record.
`customer_name`	string	No	Customer display name.
`customer_phone`	E.164	No	Customer phone for SMS receipt.
`customer_email`	email	No	Customer email for email receipt.
`department_id`	UUID	No	Department within the location.
`metadata`	object	No	Arbitrary key/value pairs stored with the order.
`level3`	object	No	Level 3 line-item data for B2B / fleet card schemes. See Level 3 data.

Response

{
  "order_id": "uuid",
  "status": "open",
  "total_cents": 5000,
  "created_at": "2024-01-15T10:30:00Z"
}

Get an order

GET /pos/v1/orders/{order_id}

Required scopes: tilt/payments:read

Returns the order with its current status and associated payments.

Response

{
  "order_id": "uuid",
  "location_id": "uuid",
  "status": "paid",
  "total_cents": 5000,
  "description": "Fleet service — invoice #INV-001",
  "external_reference": "INV-001",
  "customer_name": "Alice Example",
  "payments": [
    {
      "payment_id": "uuid",
      "status": "approved",
      "amount_cents": 5000,
      "method": "card",
      "created_at": "2024-01-15T10:30:45Z"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:45Z"
}

Order statuses

Status	Description
`open`	Created, no payment yet
`pending`	Payment initiated, awaiting processor response
`paid`	Payment approved
`partially_paid`	Partial payment applied
`voided`	Voided before settlement
`refunded`	Fully refunded
`cancelled`	Cancelled by operator or timeout