---
title: "List orders"
method: GET
path: "/api/v1/commerce/orders"
tags: ["commerce"]
---

# List orders

`GET /api/v1/commerce/orders`

## Request

- Base URL: `https://app.blueticked.com`
- URL: `https://app.blueticked.com/api/v1/commerce/orders`
- Auth: HTTP bearer

The order book, newest first: what sold, to whom, and where each order stands.

`status` filters to one of `pending`, `paid`, `failed`, `abandoned`, `refunded`; `since` (ISO 8601) returns orders created at or after that moment; `limit` caps the page (default 50, max 200).

`q` searches reference, customer name, customer email and description across the whole book. `offset` pages through results; `total` is the count matching the filters, so `offset + limit < total` means there is more.

`unfulfilled=true` returns paid orders whose goods have not gone out: the packing list, ready to poll. Add `fulfilment=delivery` or `fulfilment=collection` to split it by how the order leaves.

`fulfilled_since` (ISO 8601) returns paid orders sent or collected at or after that moment. `order=oldest` returns the longest-waiting order first (the default is `newest`).

`contact_id` (a contact's UUID) returns the orders linked to that contact: a buyer becomes a contact when their order is paid, so this lists one customer's orders even when they gave no email. A malformed id answers 400.

For accounting, `paid` and `refunded` are the only statuses that involve money having moved.

Each row is the same shape the `commerce.order.*` webhooks deliver. Store either, they never disagree.

## Query parameters

- `status` string
- `since` string
- `limit` integer

## Response `200`

Success

- object
  - `ok` boolean, required
  - `orders` object[], required
    - `id` string, uuid, required
    - `reference` string, required
    - `number` number, nullable, required
    - `paystack_reference` string, nullable, required
    - `status` 'pending' | 'paid' | 'failed' | 'abandoned' | 'refunded', required
    - `amount_cents` number, required
    - `currency` string, required
    - `description` string, nullable, required
    - `customer` object, required
      - `name` string, nullable, required
      - `email` string, email, nullable, required
      - `phone` string, nullable, required
      - `sms_marketing_opt_in` boolean, required
    - `fulfilment` object, required
      - `method` string, nullable, required
      - `delivery_address` string, nullable, required
      - `delivery_zone` string, nullable, required
      - `delivery_fee_cents` number, required
      - `fulfilled_at` string, date-time, nullable, required
      - `ready_for_collection_at` string, date-time, nullable, required
      - `tracking_reference` string, nullable, required
      - `waybill_id` string, nullable, required
      - `note` string, nullable, required
    - `discount` object, nullable, required
      - `code` string, required
      - `amount_cents` number, required
    - `payment` object, required
      - `provider` 'paystack' | 'payfast' | 'manual', required
      - `method` 'cash' | 'eft' | 'card_machine' | 'other' | 'null', nullable, required
    - `items` object[], required
      - `id` string, uuid, required
      - `product_id` string, uuid, nullable, required
      - `variant_id` string, uuid, nullable, required
      - `variant_name` string, nullable, required
      - `name` string, required
      - `unit_price_cents` number, required
      - `quantity` number, required
    - `site_id` string, uuid, nullable, required
    - `paid_at` string, date-time, nullable, required
    - `refunded_at` string, date-time, nullable, required
    - `failure_reason` string, nullable
    - `link_message_id` string, nullable
    - `emails` object, required
      - `confirmation` object
        - `state` 'sent' | 'retrying' | 'failed' | 'skipped', required
        - `at` string, date-time, required
        - `attempts` integer, required
        - `reason` 'no_buyer_email' | 'no_owner_email' | 'no_tracking_reference' | 'reserved_address' | 'message_rejected' | 'sender_not_allowed' | 'provider_rate_limited' | 'provider_unavailable' | 'send_error' | 'send_unconfirmed' | 'provider_error' | 'null', nullable, required
      - `sale_notification` object
        - `state` 'sent' | 'retrying' | 'failed' | 'skipped', required
        - `at` string, date-time, required
        - `attempts` integer, required
        - `reason` 'no_buyer_email' | 'no_owner_email' | 'no_tracking_reference' | 'reserved_address' | 'message_rejected' | 'sender_not_allowed' | 'provider_rate_limited' | 'provider_unavailable' | 'send_error' | 'send_unconfirmed' | 'provider_error' | 'null', nullable, required
      - `ready_for_collection` object
        - `state` 'sent' | 'retrying' | 'failed' | 'skipped', required
        - `at` string, date-time, required
        - `attempts` integer, required
        - `reason` 'no_buyer_email' | 'no_owner_email' | 'no_tracking_reference' | 'reserved_address' | 'message_rejected' | 'sender_not_allowed' | 'provider_rate_limited' | 'provider_unavailable' | 'send_error' | 'send_unconfirmed' | 'provider_error' | 'null', nullable, required
      - `shipped` object
        - `state` 'sent' | 'retrying' | 'failed' | 'skipped', required
        - `at` string, date-time, required
        - `attempts` integer, required
        - `reason` 'no_buyer_email' | 'no_owner_email' | 'no_tracking_reference' | 'reserved_address' | 'message_rejected' | 'sender_not_allowed' | 'provider_rate_limited' | 'provider_unavailable' | 'send_error' | 'send_unconfirmed' | 'provider_error' | 'null', nullable, required
      - `tracking` object
        - `state` 'sent' | 'retrying' | 'failed' | 'skipped', required
        - `at` string, date-time, required
        - `attempts` integer, required
        - `reason` 'no_buyer_email' | 'no_owner_email' | 'no_tracking_reference' | 'reserved_address' | 'message_rejected' | 'sender_not_allowed' | 'provider_rate_limited' | 'provider_unavailable' | 'send_error' | 'send_unconfirmed' | 'provider_error' | 'null', nullable, required
      - `refunded` object
        - `state` 'sent' | 'retrying' | 'failed' | 'skipped', required
        - `at` string, date-time, required
        - `attempts` integer, required
        - `reason` 'no_buyer_email' | 'no_owner_email' | 'no_tracking_reference' | 'reserved_address' | 'message_rejected' | 'sender_not_allowed' | 'provider_rate_limited' | 'provider_unavailable' | 'send_error' | 'send_unconfirmed' | 'provider_error' | 'null', nullable, required
    - `created_at` string, date-time, required
  - `total` number, required

## Other responses

- `400`: Validation failed
- `401`: Unauthorized: missing or invalid API key
- `402`: Insufficient wallet balance
- `403`: Forbidden: scope, plan limit, or suspension
- `404`: Not found
- `409`: Conflict (idempotency-key reuse or resource in use)
- `422`: Understood but refused: the request is well-formed, the action is not permitted for this resource
- `429`: Rate limited
- `500`: Internal error
- `502`: An upstream provider refused or failed the request
- `503`: Channel or send queue unavailable

---

[API](https://skmtc.dev/blueticked/apis/blueticked-api.md) · [All operations](https://skmtc.dev/blueticked/apis/blueticked-api/llms.txt) · [OpenAPI document](https://skmtc.dev/blueticked/apis/blueticked-api/revisions/07132284f4ff?raw)