---
title: "How the book was taken, booked quantity and value by the week it was booked in"
method: GET
path: "/api/v1/order-book/curve"
tags: ["order_book"]
---

# How the book was taken, booked quantity and value by the week it was booked in

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

## Request

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

How a season's book was taken over time: one point per week carrying the book as it stood at the end of that week, with booked quantity, booked value and line count.

`season_code` is required; `commitment_id`, `trading_partner_id` (one account's book) and `as_of` narrow as elsewhere, and `grain` takes `week`. Weekly only: a daily curve on a book taken in showroom appointments is noise around the appointments rather than a signal about the season.

It answers whether a season is ahead of or behind the pace the last one was taken at, which a single total cannot. Use get_order_book_accounts when the question is which accounts are behind rather than whether the book as a whole is.

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
- `trading_partner_id` string
- `grain` 'week'

## Headers

- `Tightly-Version` string

## Response `200`

One point per week, each with the book as it stood at the end of that week, `as_of`, `booked_qty`, `booked_value_usd` and `lines`.

- object
  - `data` object
    - `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.
    - `grain` string
    - `points` object[]
    - `scope` object
    - `scope_reason` string, 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)