---
title: "Every trading account, with its terms and how it is trading"
method: GET
path: "/api/v1/wholesale/retailers"
tags: ["wholesale"]
---

# Every trading account, with its terms and how it is trading

`GET /api/v1/wholesale/retailers`

## Request

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

Every trading account, with the identity a sell-out write and an order-book read both name an account from: its id, the account's own buyer reference, its name, its sales channel, transit time, when its data last synced, its standing terms (tier, fill-rate target, cancellation term and notice days), the next estimated order date, the trading figures read off its own reports, and `portal_seats`, the account's side of the buyer's portal: how many buyers hold a live seat, how many invitations are still unopened, and when any of them last opened it.

`retailer_ids` narrows to named accounts and `variant_id` narrows the trading figures to one variant.

Absence is never coerced. `account_tier` null means untiered and `fill_rate_target_pct` null means no promise is published; an untiered account read as the lowest tier would be deprioritised in a shortage by a policy nobody wrote. `cancellation_term` null is silence rather than `none`: read as "no term", the account's whole book would count as unwalkable and open to buy would be overstated by exactly the value that can still cancel, so `cancellation_term_note` carries the absence instead.

`accepts_855`/`856`/`810` null: nobody asked.

Use this to resolve an account id before posting sell-out. The writes on this prefix configure the integration rather than describe an account, and are not public.

Sold with Essentials+: without Tightly Connect the answer is 403 `plan_excludes`. A key issued to one account sees that account alone here.

Scope: `accounts:read`.

## Query parameters

- `retailer_ids` string
- `variant_id` string

## Headers

- `Tightly-Version` string

## Response `200`

`retailers`, one row per account, with identity, channel, terms, the cadence of its orders, the trading figures read off its own reports and, where the seat store answered, `portal_seats` with `accepted`, `invited` and `last_opened_at`.

`sales_velocity_per_week` is null where none of the account's recent weekly periods carries a units-sold figure: it reports only whole calendar months, reports stock without sales, or has not reported yet. A month is never divided into weeks, and a week that sold nothing still reads 0.

- object
  - `data` object
    - `data_source` 'rollup' | 'live': Which store answered `sales_velocity_per_week` and the next estimated order: `rollup` when every account's figures were kept at write time, `live` when at least one account was computed on this request because a sale or sell-out for it was written since. The figures are the same either way. Absent when there are no accounts.
    - `live_account_ids` string[]: The accounts whose two figures were computed on this request; every other account's came off the kept figures. Empty when `data_source` is `rollup`.
    - `retailers` object[]
  - `message` object: severity, service and desc.

## Other responses

- `401`: No usable key: malformed, unknown, revoked, expired or stopped. One refusal covers all five, telling a caller which is which maps the surface for them. A request with no Authorization header at all is refused 400 before any key is looked for.
- `403`: The key may not reach this operation. `plan_excludes` when Accounts is sold with Essentials+ and this organisation's plan does not include it; `scope_missing` when the key does not hold Accounts; `organization_mismatch` when the path names an organisation that is not the key's; `ip_not_allowed` when the caller's address is outside the key's allowlist.
- `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)