# Orders

Order retrieval, fulfillment tracking, and cancellation.

## List orders

 - [GET /orders](https://tote.redocly.app/online-ordering/spec/openapi/orders/listorders.md): Returns a paginated list of orders accessible to your API credentials.
Results are ordered by creation date (newest first).

Pagination: Results use cursor-based pagination. Use the cursor
parameter from the pagination.next_cursor field to retrieve the next page.

Filtering: Combine filters to narrow results. All filters are optional
and applied with AND logic:
- status: Filter by order lifecycle status (e.g., CONFIRMED, COMPLETED).
- fulfillment_status: Filter by fulfillment stage (e.g., PREPARING, READY_FOR_PICKUP).
- location_id: Filter by store location.
- customer_id: Filter by customer identifier (exact match).
- date_from / date_to: Filter by creation date range.

Response format: Returns OrderSummary objects (lightweight, no items
or payments arrays). Use GET /orders/{order_id} for the full order detail.

## Get order details

 - [GET /orders/{order_id}](https://tote.redocly.app/online-ordering/spec/openapi/orders/getorder.md): Returns the full order resource including line items, payments, all three
status fields, financial totals, and handoff details.

Status fields:
- status: Order lifecycle (PENDING, CONFIRMED, COMPLETED, etc.)
- payment_status: Aggregate payment state (UNPAID, PROCESSING, PARTIALLY_PAID, PAID)
- fulfillment_status: Physical fulfillment progress (PENDING through FULFILLED/DELIVERED)

Polling for updates: After submitting a payment, poll this endpoint
to check the updated payment_status and balance_due. Recommended
polling interval: 2 seconds, with exponential backoff up to 30 seconds.
Stop polling when payment_status reaches PAID or the payment reaches a
terminal state.

Payments array: The payments array contains all payments attached to
this order, including their individual statuses. Use this to display
payment history and determine if additional payments are needed for
split-pay scenarios.

## Cancel an order

 - [POST /orders/{order_id}/cancel](https://tote.redocly.app/online-ordering/spec/openapi/orders/cancelorder.md): Cancels an order that has not yet started preparation. This endpoint is
only available when fulfillment_status is PENDING or IN_PROGRESS.

Fulfillment restriction: Once the store begins preparing the order
(fulfillment_status is PREPARING or later), this endpoint returns 409
Conflict. Cancellation at that stage requires store intervention.

Automatic void/refund: When an order is cancelled, the server
automatically handles all attached payments:
- Payments in PENDING or AUTHORIZED status are voided (no charge).
- Payments in CAPTURED or COMPLETED status are refunded in full.
- Refunds follow the minimize-cash-refund strategy: loyalty points are
  refunded first, then gift cards, then credit/debit cards.

No separate refund request is needed after cancellation.

Idempotency: This endpoint requires the Idempotency-Key header.
If the order was already cancelled with the same key, the server returns
the current order state without re-processing.

Result: The order's status is set to CANCELLED, fulfillment_status
is set to CANCELLED, and all payments are voided or refunded.