---
title: "Every account's book against its own prior season, read at the same days before start"
method: GET
path: "/api/v1/order-book/accounts"
tags: ["order_book"]
---

# Every account's book against its own prior season, read at the same days before start

`GET /api/v1/order-book/accounts`

## Request

- Base URL: `https://api.app.tightly.io`
- URL: `https://api.app.tightly.io/api/v1/order-book/accounts`
- Auth: HTTP bearer

One row per account: this season's booked quantity and value, and the same account's prior-season book read at the same number of days before the season started shipping, with each account's identity and reference. `held_qty` is the hold units already inside `booked_qty`, never beside it: a hold has no price, so it moves the booked quantity and not the value. `booked_priced_qty` is `booked_qty`'s priced subset, what `booked_value_usd` is averaged over.

`season_code` is required; `prior_season_code`, `season_start` and `prior_season_start` state the anchors, `commitment_id` narrows to one Commitment, `as_of` reads the book at an instant, so a half-taken book is never compared with a finished one.

`trading_partner_id` is the identity and `name` only what to show, since account names repeat; `account_reference` is the account's own reference, with `account_reference_reason` where there is none.

`prior` is null where the prior season has no book at all; a zero inside it means the book exists and this account had nothing booked then. `anchors.prior_reason` says why there is none.

`predicted_qty` is what we expect this account's doors to sell, beside `booked_qty`: under ordered accounts are one subtraction away. Null where nothing is sized, absent where unreadable, never 0. `doors_reporting` of `doors_on_file` is how much of the estate the prediction stands on.

Sold with Essentials+: without Tightly Connect the answer is 403 `plan_excludes`.

Scope: `order_book:read`.

## Query parameters

- `season_code` string, required
- `commitment_id` string
- `as_of` string, date-time
- `prior_season_code` string
- `season_start` string, date
- `prior_season_start` string, date

## Headers

- `Tightly-Version` string

## Response `200`

`t_minus_days`, the two season anchors with their sources, and one row per account holding a line in either season, each with `booked_qty`, `booked_value_usd`, `prior`, `doors_reporting`, `doors_on_file`, `predicted_qty` and, where the held share was readable, `held_qty`.

Each row also carries the season's demand from the account, as the Commitment's wholesale leg carries it: `demand_units`, `demand_value_usd` (at the account's own wholesale price, null where it has no priced line), `demand_cost_usd`, `demand_value_basis`, `demand_source` (`sell_out` where it stands on the account's own sell-out, `sell_in` where on what you ship them), `demand_note`, and `gap`, the demand the book has not yet taken. They are null where none is measured, with `demand_unavailable_reason`; `demand_commitment_id` names the Commitment read and `demand_reason` says why a page carries none. Beside them: `shown_at`, `shown_state` and `showing_id` (the latest showing), `portal_seats` (`accepted`, `invited`, `last_opened_at`) and `waits_on_you`, four counts (`claims`, `asks`, `order_files` at the `needs_you` stage, `door_types`), each null where that kind cannot be read.

- object
  - `data` object
    - `accounts` object[]
    - `anchors` object: The current and prior season starts, each labelled declared or derived, plus prior_reason.
    - `as_of` string, date-time
    - `currency` object: What the figures below are in. `functional` is the book's own currency and the denomination every amount here carries. `_usd` in a key name is the book's functional currency for historical reasons, never a claim of dollars. `transaction` is what the lines were agreed in where they agree on one, and null where they do not; `reporting` is what a reader of this organisation asked to see, with `rate` the dated rate between the last two, served, never applied, and dated to this read's `as_of` so a re-read of a past instant cannot move. `basis` is one of same, converted or unconverted, and `reason` carries the absence word where the block cannot say something.
    - `demand_commitment_id` string, nullable: The Commitment whose married demand the accounts' demand fields read; null where there is none or more than one.
    - `demand_reason` string, nullable: Why the page carries no demand figures; null where it does.
    - `scope` object
    - `t_minus_days` integer, nullable
  - `message` object: severity, service and desc.

## Other responses

- `400`: A required parameter is missing, or a date could not be read.
- `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 Order book is sold with Essentials+ and this organisation's plan does not include it; `scope_missing` when the key does not hold Order book; `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; `account_mismatch` when a key issued to one account calls this read, whose figure covers every account on the book; the sentence names `GET /order-book/account-styles` and `GET /order-book/account-anchor`, which are that account's own.
- `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)