---
title: "What is booked for a season, and the one envelope comparison that is like-for-like"
method: GET
path: "/api/v1/order-book/summary"
tags: ["order_book"]
---

# What is booked for a season, and the one envelope comparison that is like-for-like

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

## Request

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

The headline of a wholesale book for one season: booked quantity and value, lines, accounts, the split by status and by channel, the buy envelope the book runs against with open to buy, the prebook against at-once split, and the firm, walkable and unknown split of the committed value.

`season_code` is required, `commitment_id` narrows to one Commitment, `as_of` reads the book as it stood at an instant, and `season_start` overrides the season anchor the prebook split is measured against.

`book` is null when the scope has no lines at all, and so is `envelope`: a season nobody has booked into is not a season booked to zero. A hold adds its quantity to `booked_qty` and nothing to `booked_value_usd`, so `soft_qty` and `committed_qty` are served beside them, because an unpriced hold's value is unstated rather than zero.

Totals only. Use get_order_book_firmness for the per-account exposure and the cancellation ladder, get_order_book_accounts for the account-by-account comparison, and get_order_book_curve for how the book was taken over time. All four read the same book, so a figure from one cannot disagree with a figure from another.

The book stays in the organisation's functional currency: `_usd` in a key name is historical, so on a sterling book `booked_value_usd` carries pounds. Every order book read serves the same `currency` block.

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
- `season_start` string, date

## Headers

- `Tightly-Version` string

## Response `200`

The book, its envelope, the prebook / at-once split with the anchor it was measured against, and the firm / walkable / unknown split of the committed value.

- object
  - `data` object
    - `as_of` string, date-time
    - `book` object, nullable: booked_qty, booked_value_usd, lines, accounts, the soft share, by_status and by_channel. Null where the scope holds no lines.
    - `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.
    - `envelope` object, nullable: The buy envelope this book is measured against, or null where there is no book to compare.
    - `firmness` object: Firm, walkable and unknown value, how much of booked_value_usd is a retailer's option.
    - `scope` object: The season code and commitment id actually read.
    - `scope_reason` string, nullable
    - `split` object: Prebook against at-once, with the season anchor and whether it was declared or derived.
    - `unattributable` object: Book value the scope could not attribute, and why.
  - `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)