---
title: "list sales orders"
method: GET
path: "/api/v1/sales/orders"
tags: ["orders"]
---

# list sales orders

`GET /api/v1/sales/orders`

## Request

- Base URL: `https://api.app.tightly.io`
- URL: `https://api.app.tightly.io/api/v1/sales/orders`
- Auth: HTTP bearer

Every order Tightly holds, whatever it came in by: a connected channel, a person, a file, this API, an EDI 850 or the buyer portal. `status_numbers` counts the whole filtered book per lifecycle, not the page, so a total shown above the rows can be relied on. Do not call this to find one order you already have the id for: `GET /sales/orders/{order_id}` serves that one whole, and this list deliberately carries no address.

Scope: `orders:read`.

## Query parameters

- `product_query` string
- `lifecycle` 'draft' | 'open' | 'allocated' | 'fulfilment_requested' | 'fulfilled' | 'cancelled'
- `needs_you` boolean
- `origin` 'channel' | 'manual' | 'csv' | 'api' | 'edi' | 'portal'
- `is_wholesale` boolean
- `trading_partner_id` string
- `sales_channel_id` string
- `location_ids` string
- `commitment_ids` string
- `search` string
- `since` string, date
- `offset` integer
- `limit` integer
- `sort_key` 'name' | 'customer' | 'origin' | 'state' | 'placed' | 'value' | 'units' | 'channel' | 'location' | 'needs'
- `sort_dir` 'asc' | 'desc'

## Headers

- `Tightly-Version` string

## Response `200`

The page of orders, and the counts the head ties to.

- object
  - `data` object: The house paging shape (offset, size, max_size, filtered_max_size, rows), status_numbers and as_of.
  - `message` object: severity, service and desc.

## Other responses

- `400`: A filter carries a value the list does not offer, or `since` is not a date written YYYY-MM-DD (`date_unreadable`).
- `401`: No usable key: malformed, unknown, revoked, expired or stopped.
- `403`: The key does not hold Orders (`scope_missing`), or is issued to one account and named another (`account_mismatch`).
- `429`: The key has spent its allowance for this minute. 600 reads and 120 writes a minute, counted per key, refused calls included. `Retry-After` says how long to wait.
- `503`: The database is briefly out of reach, which is what a failover or a full connection pool looks like from outside. Wait the seconds `Retry-After` names and send the request again. A read is safe to repeat. A write is not, because the connection was lost in the middle of it, so read the object back before sending it a second time. Branch on the status rather than on `code`, which is `POSTGRES_UNAVAILABLE` from one of the two seams that raise this and `SERVICE_UNAVAILABLE` from the other.

---

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