---
title: "Every order file that has arrived, newest first"
method: GET
path: "/api/v1/sales/orders/documents"
tags: ["orders"]
---

# Every order file that has arrived, newest first

`GET /api/v1/sales/orders/documents`

## Request

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

Every purchase order a retailer has sent you, whichever door it came through: a mail attachment, a followed link, an upload, a buyer's own send through their seat, or an 850 over EDI. Each row says what state the paper is in, what Tightly read off it, and which draft order it became.

Filter by `state` to find the papers waiting on somebody, by `lane` to find one door's, or by `trading_partner_id` for one account's. `state` also takes `needs_you`, `ready` and `confirmed`: who acts next, read from the paper and the draft order it made together.

Scope: `orders:read`.

## Query parameters

- `state` 'received' | 'parsed' | 'applied' | 'refused' | 'queued' | 'sent' | 'failed' | 'needs_you' | 'ready' | 'confirmed'
- `lane` 'upload' | 'email' | 'link' | 'portal' | 'sps_commerce'
- `trading_partner_id` string
- `since` string, date
- `limit` integer
- `offset` integer

## Headers

- `Tightly-Version` string

## Response `200`

The papers, and the counts a head ties to.

- object
  - `data` object
  - `message` object

## Other responses

- `401`: No usable key: malformed, unknown, revoked, expired or stopped. One refusal covers all five.
- `403`: The key may not reach this operation. `plan_excludes` when this organisation's plan does not include Tightly Connect, which the arriving order file needs and which is sold with Essentials+; `scope_missing` when the key does not hold Orders; `ip_not_allowed` when the caller's address is outside the key's allowlist; `account_mismatch` when a key issued to one account names another, or a paper that is not that account's.
- `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)