# List orders

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.

Endpoint: GET /orders
Version: 1.0.0
Security: oauth2

## Query parameters:

  - `cursor` (string)
    Opaque cursor for pagination. Obtained from the next_cursor field of a previous response.

  - `limit` (integer)
    Maximum number of results to return per page.

  - `status` (string)
    Filter orders by lifecycle status. Accepts a single value.
See OrderStatus enum for valid values.
    Enum: "PENDING", "CONFIRMED", "COMPLETED", "FAILED", "VOIDED", "CANCELLED"

  - `fulfillment_status` (string)
    Filter orders by fulfillment status. Accepts a single value.
See FulfillmentStatus enum for valid values.
    Enum: "PENDING", "IN_PROGRESS", "PREPARING", "READY_FOR_PICKUP", "FULFILLED", "DELIVERED", "RETURNED", "CANCELLED"

  - `location_id` (string)
    Filter orders by location (store). Returns only orders placed at
the specified location.

  - `date_from` (string)
    Filter orders created on or after this date-time (inclusive).
ISO 8601 format (e.g., 2026-01-01T00:00:00Z).

  - `date_to` (string)
    Filter orders created on or before this date-time (inclusive).
ISO 8601 format (e.g., 2026-01-31T23:59:59Z).

  - `customer_id` (string)
    Filter orders by customer identifier. Returns only orders where
customer_id matches exactly (case-sensitive). Use this to look up
a customer's order history.
    Example: "CUST-12345"

## Response 200 fields (application/json):

  - `data` (array, required)
    List of order summaries.

  - `data.id` (string, required)
    Unique identifier for the order.

  - `data.location_id` (string, required)
    The location (store) this order belongs to.

  - `data.customer_id` (string,null)
    Customer identifier for this order. Null for anonymous orders.
Use GET /orders?customer_id=X to find orders by customer.

  - `data.status` (string, required)
    Order lifecycle status. Tracks the high-level state of the order from
creation through completion or cancellation.

- PENDING: Order created from cart checkout, awaiting payment.
- CONFIRMED: At least one payment completed; order accepted by the store.
- COMPLETED: Order fulfilled and closed.
- FAILED: Order could not be processed (e.g., all payments failed).
- VOIDED: Order voided before any fulfillment began.
- CANCELLED: Order cancelled by customer or system.

State transitions:
- PENDING -> CONFIRMED, FAILED, VOIDED, CANCELLED
- CONFIRMED -> COMPLETED, CANCELLED
- COMPLETED, FAILED, VOIDED, CANCELLED are terminal (no further transitions)
    Enum: "PENDING", "CONFIRMED", "COMPLETED", "FAILED", "VOIDED", "CANCELLED"

  - `data.payment_status` (string, required)
    Aggregate payment status across all payments on the order. This is a
server-computed summary -- do not set directly.

- UNPAID: No payments submitted yet.
- PROCESSING: At least one payment is in a non-terminal state (PENDING or AUTHORIZED).
- PARTIALLY_PAID: Some payments completed but total paid = order total. The order is fully covered.

State transitions:
- UNPAID -> PROCESSING, PARTIALLY_PAID, PAID
- PROCESSING -> PARTIALLY_PAID, PAID, UNPAID (if all payments fail)
- PARTIALLY_PAID -> PROCESSING, PAID
- PAID is terminal for forward flow (refunds revert to PARTIALLY_PAID or UNPAID)
    Enum: "UNPAID", "PROCESSING", "PARTIALLY_PAID", "PAID"

  - `data.fulfillment_status` (string, required)
    Fulfillment lifecycle status. Tracks the physical preparation and handoff
of the order. Maps directly from the backend fulfillment state machine.

- PENDING: Order created, not yet accepted by store.
- IN_PROGRESS: Store accepted the order and is queuing it.
- PREPARING: Store staff actively assembling the order.
- READY_FOR_PICKUP: Order assembled and waiting for customer (pickup/curbside).
- FULFILLED: Customer received the order (pickup/curbside/kiosk).
- DELIVERED: Order delivered to customer address (delivery orders).
- RETURNED: Order returned after fulfillment.
- CANCELLED: Fulfillment cancelled before completion.

State transitions:
- PENDING -> IN_PROGRESS, CANCELLED
- IN_PROGRESS -> PREPARING, CANCELLED
- PREPARING -> READY_FOR_PICKUP, CANCELLED
- READY_FOR_PICKUP -> FULFILLED, DELIVERED, CANCELLED
- FULFILLED -> RETURNED
- DELIVERED -> RETURNED
- RETURNED, CANCELLED are terminal (no further transitions)

Cancellation restriction: Orders can only be cancelled via
POST /orders/{order_id}/cancel when fulfillment_status is PENDING or
IN_PROGRESS. Once preparation begins, cancellation requires store
intervention.
    Enum: "PENDING", "IN_PROGRESS", "PREPARING", "READY_FOR_PICKUP", "FULFILLED", "DELIVERED", "RETURNED", "CANCELLED"

  - `data.item_count` (integer, required)
    Total number of line items in the order.

  - `data.handoff_mode` (string)
    The handoff mode for this order.
    Enum: "PICKUP", "CURBSIDE", "DELIVERY", "KIOSK"

  - `data.promo_codes` (array)
    Promo codes applied to this order.

  - `data.promo_codes.code` (string, required)
    The promo code string, normalized to uppercase. Codes are case-insensitive
on input ("summer25" and "SUMMER25" are treated identically) but always
returned as uppercase in responses.
    Example: "SUMMER25"

  - `data.promo_codes.status` (string, required)
    Current status of this promo code on the cart.
- ACTIVE: The code is applied and its discount is reflected in totals.
- EXPIRED: The code expired after being applied (e.g., time-limited promo).
- REDEEMED: The code was already used (single-use codes) and locked at checkout.
    Enum: "ACTIVE", "EXPIRED", "REDEEMED"

  - `data.promo_codes.discount_preview` (object)
    Estimated discount this promo code provides. Present when the code is
ACTIVE. The actual discount amount appears in the PriceCalculation
discounts array with source: PROMO_CODE.

  - `data.promo_codes.discount_preview.estimated_discount` (object)
    Estimated discount amount in cents.

  - `data.promo_codes.discount_preview.estimated_discount.amount` (integer, required)
    Monetary value in the smallest currency unit (cents for USD).
Example: 1299 = $12.99.
    Example: 1299

  - `data.promo_codes.discount_preview.estimated_discount.currency` (string, required)
    ISO 4217 currency code.
    Example: "USD"

  - `data.promo_codes.discount_preview.description` (string)
    Human-readable description of the discount.
    Example: "25% off your order (up to $10)"

  - `data.promo_codes.applied_at` (string, required)
    When this promo code was applied to the cart.

  - `data.total` (object, required)
    Grand total for the order.

  - `data.total_paid` (object)
    Sum of all completed payment amounts.

  - `data.balance_due` (object)
    Remaining amount to be paid.

  - `data.created_at` (string, required)
    When the order was created.

  - `data.updated_at` (string, required)
    When the order was last modified.

  - `pagination` (object, required)

  - `pagination.has_more` (boolean, required)
    Whether more results exist beyond this page.

  - `pagination.next_cursor` (string,null)
    Opaque cursor for the next page. Pass as the cursor query parameter.
Null when there are no more results.

## Response 401 fields (application/json):

  - `error` (object, required)

  - `error.code` (string, required)
    Machine-readable error category. Use this field for programmatic
error handling (e.g., retry on RATE_LIMIT_ERROR, re-authenticate
on AUTHENTICATION_ERROR).
    Enum: "AUTHENTICATION_ERROR", "INVALID_REQUEST_ERROR", "RATE_LIMIT_ERROR", "NOT_FOUND_ERROR", "CONFLICT_ERROR", "INTERNAL_ERROR"

  - `error.message` (string, required)
    Human-readable error description. Safe to display to developers
in logs or debugging tools. Do not display to end users.

  - `error.detail` (string)
    Additional context about the error, including suggestions for
resolution. May include specific field values or limits that
were exceeded.

  - `error.request_id` (string, required)
    Unique identifier for this request. Include this value when
contacting Tote Developer Support for troubleshooting.

  - `error.field` (string,null)
    JSON pointer to the field that caused the error.
Null if the error is not field-specific.
    Example: "items[0].modifier_groups[1].modifiers"

  - `error.change_reasons` (array)
    Machine-readable reasons why the resource state changed, causing
the conflict. Present on checkout 409 responses when expected_total
does not match the current total. Clients should re-fetch the cart
and call POST /carts/{cart_id}/calculate to get the updated total
before retrying checkout.
    Enum: "PROMO_EXPIRED", "DISCOUNT_CHANGED", "ITEM_PRICE_CHANGED", "ITEM_UNAVAILABLE", "FEE_CHANGED"

## Response 429 fields (application/json):

  - `error` (object, required)

  - `error.code` (string, required)
    Machine-readable error category. Use this field for programmatic
error handling (e.g., retry on RATE_LIMIT_ERROR, re-authenticate
on AUTHENTICATION_ERROR).
    Enum: "AUTHENTICATION_ERROR", "INVALID_REQUEST_ERROR", "RATE_LIMIT_ERROR", "NOT_FOUND_ERROR", "CONFLICT_ERROR", "INTERNAL_ERROR"

  - `error.message` (string, required)
    Human-readable error description. Safe to display to developers
in logs or debugging tools. Do not display to end users.

  - `error.detail` (string)
    Additional context about the error, including suggestions for
resolution. May include specific field values or limits that
were exceeded.

  - `error.request_id` (string, required)
    Unique identifier for this request. Include this value when
contacting Tote Developer Support for troubleshooting.

  - `error.field` (string,null)
    JSON pointer to the field that caused the error.
Null if the error is not field-specific.
    Example: "items[0].modifier_groups[1].modifiers"

  - `error.change_reasons` (array)
    Machine-readable reasons why the resource state changed, causing
the conflict. Present on checkout 409 responses when expected_total
does not match the current total. Clients should re-fetch the cart
and call POST /carts/{cart_id}/calculate to get the updated total
before retrying checkout.
    Enum: "PROMO_EXPIRED", "DISCOUNT_CHANGED", "ITEM_PRICE_CHANGED", "ITEM_UNAVAILABLE", "FEE_CHANGED"

## Response 500 fields (application/json):

  - `error` (object, required)

  - `error.code` (string, required)
    Machine-readable error category. Use this field for programmatic
error handling (e.g., retry on RATE_LIMIT_ERROR, re-authenticate
on AUTHENTICATION_ERROR).
    Enum: "AUTHENTICATION_ERROR", "INVALID_REQUEST_ERROR", "RATE_LIMIT_ERROR", "NOT_FOUND_ERROR", "CONFLICT_ERROR", "INTERNAL_ERROR"

  - `error.message` (string, required)
    Human-readable error description. Safe to display to developers
in logs or debugging tools. Do not display to end users.

  - `error.detail` (string)
    Additional context about the error, including suggestions for
resolution. May include specific field values or limits that
were exceeded.

  - `error.request_id` (string, required)
    Unique identifier for this request. Include this value when
contacting Tote Developer Support for troubleshooting.

  - `error.field` (string,null)
    JSON pointer to the field that caused the error.
Null if the error is not field-specific.
    Example: "items[0].modifier_groups[1].modifiers"

  - `error.change_reasons` (array)
    Machine-readable reasons why the resource state changed, causing
the conflict. Present on checkout 409 responses when expected_total
does not match the current total. Clients should re-fetch the cart
and call POST /carts/{cart_id}/calculate to get the updated total
before retrying checkout.
    Enum: "PROMO_EXPIRED", "DISCOUNT_CHANGED", "ITEM_PRICE_CHANGED", "ITEM_UNAVAILABLE", "FEE_CHANGED"