# Fynex Billing API — integration reference

Base URL: `https://api.fynex.ai/billing-api/v1` in production,
`https://staging-api.fynex.ai/billing-api/v1` for sandbox work. The examples
below use `$FYNEX_API_BASE` for whichever of the two you are on, as the rest of
these guides do. Your key decides which data you see: a `sk_test_…` key is test
mode wherever you send it, a `sk_live_…` key is live. This REST API is the only
supported external billing surface; internal GraphQL is never part of the
contract.

## Call convention

Send `Authorization: Bearer sk_test_…` or `Authorization: Bearer sk_live_…`
on every operation. Publishable keys, dashboard sessions, cookies, legacy
tokens and query-string credentials are rejected. The secret key defines the
seller tenant; another seller's id is indistinguishable from a missing id
(`404`). All responses include `X-Request-Id`; provide it to support. Clients
must ignore unknown response fields and tolerate unknown enum values.

Amounts are integer minor units with the resource's ISO 4217 `currency`.
Quantities, rates and percentages are decimal strings. Times are RFC 3339 UTC;
date-only invoice filters mean UTC midnight. Do not use floating-point money.

Lists use keyset paging: request `limit` (1–100, default 20), then pass
`nextCursor` back as `cursor` while `hasMore` is true — the same loop on every
list. Contracts walk forward by ascending id; every other list is newest
first. The original directional names (`beforeId`/`nextBeforeId`,
`afterId`/`nextAfterId`) still work and are still returned.

| Status | Meaning | Retry |
| --- | --- | --- |
| `400` | Invalid id, filter, paging or date parameter | Fix request |
| `401` / `403` | Invalid key / inactive seller | Fix credentials or account |
| `404` | Missing or foreign resource | No |
| `422` | Valid request cannot apply in current state | Wait for state change |
| `429` | Seller budget exhausted | Wait `Retry-After` |
| `5xx` | Fynex fault | Retry with exponential backoff and jitter |

Error bodies are `{"error":"message"}`. Rate-limit headers are advisory:
read `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `Retry-After` instead
of hard-coding a quota.

## Operations

| Method and path | Use |
| --- | --- |
| `GET /contracts` | Find contracts (`cursor`, `limit`; walks forward). |
| `GET /contracts/{contractId}/usage` | Current open-period metric usage. Empty metrics is valid. |
| `GET /contracts/{contractId}/credits` | Complete balances and paged immutable ledger. |
| `GET /credits` | Seller-wide credit balances. May return `501` when credits are disabled. |
| `GET /invoices` | Newest-first invoices; filter by contract, customer, origin, status, type, correction, and issue range. |
| `GET /invoices/{invoiceId}` | Invoice plus immutable lines and frozen buyer identity. |
| `GET /invoices/{invoiceId}/pdf` | Rendered legal document. |
| `POST /invoices/{invoiceId}/send` | Create or return the invoice's hosted collection link. |
| `GET /subscriptions` / `GET /subscriptions/{subscriptionId}` | Recurring billing state and price. |
| `POST /prices/evaluate` | What a pricing configuration charges at given quantities — the billing engine, pure. |

The generated [OpenAPI document](./openapi.json) is the typed source of truth
for every parameter and response field. The interactive version is
[`/billing-api/v1/docs`](./docs).

## Invoice collection

`POST /invoices/{invoiceId}/send` takes no idempotency header: the invoice id is
itself the collection anchor, so a transport retry — and any concurrent call —
converges on one payment link and does not send another invitation. The action is unavailable (`422`) for a
bank-transfer invoice, draft/paid/voided/written-off invoice, or one with no
collectible balance.

Invoices and credit-ledger rows are immutable. Corrections are separate credit
notes; never expect a historical invoice to be edited or deleted. To determine
whether an invoice is settled, use `status` and `paidVia`, not
`collectibleMinor` or `creditSettledMinor`.

Billing emits signed webhooks on the shared notify pipe: `InvoiceIssued`,
`InvoiceSent`, `InvoicePaid`, `InvoiceOverdue`, `InvoiceVoided`,
`InvoiceWrittenOff`, `CreditApplied`, `CreditDepleted`, and the ten
`BillingSubscription*` lifecycle events — staged in the same transaction as
the state change, delivered with `X-Fynex-Signature` (HMAC-SHA256 of the raw
body) and `X-Fynex-Timestamp`, and retried until 2xx. The body is an envelope
(`eventId`, `eventType`, `sellerAccountUuid`, `occurredAt`) with the event's
fields under `payload`; every event is typed in the OpenAPI document's
`webhooks` block. Polling `GET /invoices` with a bounded issue-date range
remains the right tool for reconciliation.

## Metered usage

This API reads the meter; the write half is `/billing-api/v1/usage`, same
secret key (it also answers on the older `/usage/v1` prefix). `POST
/billing-api/v1/usage/metrics` registers a meter (`name`,
`unit`, `aggregation`: sum/max/min/last/count/count_unique — the last
requires `uniqueKey`, the metadata key counted distinct, capped at 1000
values per period). `PUT
/billing-api/v1/usage/contracts/{contractId}/metrics/{metricName}/price` sets its
pricing —
scheme `per_unit`, `graduated`, `volume`, `tiered`, `package` or
`percentage`, with included units,
rollover and commitment floors/caps; rates there are decimal strings in MAJOR
units, unlike every amount this API returns. `POST /billing-api/v1/usage/events` reports one event (`contractId`, `metric`, `quantity` as a decimal string,
`occurredAt`, `idempotencyKey`), `:batch` reports many, `/billing-api/v1/usage/csv` takes a file. A `201` with `"metered": false` means the event was stored but no active
subscription schedule covers `occurredAt` — it will not be billed. There are
no write endpoints for contracts, subscriptions, invoices or credits.

## Compatibility and lifecycle

The `/v1` path is the major-version contract. Additive fields and endpoints
may appear without a version change; removing or renaming a field, changing a
type or meaning, adding a required request value, narrowing an enum, or
changing money semantics requires a new major version and a published
migration notice. Invoice statuses are `draft`, `issued`, `sent`, `paid`,
`overdue`, `voided`, and `written_off`; subscriptions expose their current
status and scheduled cancellation or price change fields.

---

# Fynex Billing API

The Billing API is the public, versioned REST surface for billing data:
invoices, subscriptions, contracts, metered usage, and credit balances. Your
systems read the documents the billing engine issues, raise collection on
them, and write the metering that drives them — see **What v1 does, and what
it does not** below for exactly where that line falls.

All endpoints live under the path prefix:

```
/billing-api/v1
```

The host depends on the environment you were onboarded to — see **Base URL**
in the Quickstart. Throughout these guides examples use `$FYNEX_API_BASE`,
which you set once to your host plus that prefix.

Authenticate every request with your seller secret key (`sk_test_…` or
`sk_live_…`) in the `Authorization` header.

**New here? Read Concepts first** — five objects and the relationships
between them, in two minutes. **Then the Quickstart**, which goes from issuing
a key to listing invoices and downloading a PDF. Then:

| Guide | What it covers |
| --- | --- |
| Concepts | The five objects, how they relate, and the three questions their names do not answer. |
| Quickstart | Your first calls, and what each failure status means. |
| Authentication | Key format, environments, rotation, failure contract. |
| Errors | Status contract, rate limits, what is safe to retry. |
| Sandbox & testing | Hosts, keys, test cards, how to exercise date-driven flows without waiting, and the flags a sandbox needs on. |
| Pagination & Amounts | The keyset paging loop; minor units and decimal strings. |
| Endpoint reference | Every operation in detail: parameters, response fields, failure modes, worked examples. |
| Workflows | Collecting on an invoice, polling for settlement, reconciling a period, watching usage and credit. |
| Usage ingestion | The write half of metered billing: metrics, pricing schemes, events, inbound webhooks, and the price preview. |
| Webhooks | The billing event catalog: invoice lifecycle and credit events, signing, retries. |
| Code examples | Paging and retry loops in Python, Node, Go and shell; generating a typed client. |

## What v1 does, and what it does not

The line runs between **documents** and **metering**, not between reads and
writes.

**Every object this API lists can also be created through it.** The line
that remains is between *creating* a document and *editing* one: contracts
are amended by appending a version, invoices are corrected by issuing a credit
note, and neither is ever changed in place.

**Six surfaces are writable.**

- **Contracts.** `POST /contracts` creates one in `draft` for a customer you
  own (with a required `Idempotency-Key`), and
  `POST /contracts/{contractId}/amendments` appends a version — a status move,
  new dates, a replaced component set — guarded by the `expectedBaseVersion`
  you last read. Closing a contract does not cancel its subscriptions: cancel
  those first — see **Contracts**.
- **Invoices.** `POST /invoices` composes, numbers and (by default) sends a
  document in one call, with a required `Idempotency-Key`; it is immutable
  from the moment it is issued — see **Invoices**. `POST /invoices/{invoiceId}/send`
  raises or re-raises the collection link.
- **Subscriptions.** `POST /contracts/{contractId}/subscriptions` creates one
  on a contract you own (with a required `Idempotency-Key`), and
  `/subscriptions/{subscriptionId}/cancel`, `/pause`, `/resume`, `/end-trial`
  and `/change-plan` drive its lifecycle — see **Subscriptions**. Marking a
  subscription past-due or recovered is not yours to do: that is the
  collection loop's verdict.
- **Credit top-ups.** `POST /contracts/{contractId}/credits/top-up` grants a
  credit lot on a contract you own, with a required `Idempotency-Key` whose
  body *is* compared — see **Credits**. It is the only way credit enters the
  ledger; the deductions, expiries and reversals that take it out are the
  engine's rows.
- **Customers.** `POST /customers` resolves one of your customers by e-mail,
  creating the record when the address is new — the `sellerCustomerId` every
  contract, credit grant and invoice refers to. No `Idempotency-Key`: the
  address is the key, so the call always answers `200`.
- **Metering**, described in full two paragraphs down.

Read-only does not mean static. On a seller who has them enabled, background
passes issue invoices for due subscription terms and closed usage, and charge
sent invoices against the customer's saved card. So a list can grow and a
document can reach `paid` with no call of yours — see **Sandbox & testing**
for the switches that decide it.

**Metering is fully writable.** Registering a metric, pricing it, sending
events and previewing what a configuration charges are all part of this API —
see the two paragraphs below and the **Usage ingestion** guide. Nothing about
metered billing requires the dashboard.

Issued documents stay immutable either way: corrections are new credit notes,
never edits.

**Billing emits webhooks** — `InvoiceIssued`/`Sent`/`Paid`/`Overdue`/`Voided`/
`WrittenOff` and `CreditApplied`/`CreditDepleted` — through the same signed
delivery pipe as payment events: one receiver handles both. See the
**Webhooks** guide. Polling `GET /invoices` remains the right tool for
reconciliation.

**Metered usage is reported under `/billing-api/v1/usage`**: register a
metric, price it, then send events singly, in batches or by CSV. That is what
`GET /billing-api/v1/contracts/{contractId}/usage` reads back. The **Usage
ingestion** guide documents it end to end.

Two related surfaces are documented separately and are **not** duplicated
here:

- **Payments API** (`/payments-api/v1`) — payments, payouts, wallets,
  webhooks, and **top-up invoices**.
- **Payment Links API** (`/api/v1/payment-links`) — standalone payment-link
  management. Billing invoices create their own collection links via
  `POST /billing-api/v1/invoices/{invoiceId}/send`; the resulting hosted
  payment page URL is returned on the invoice itself.

---

# Overview

## Resources

| Resource | What it is |
| --- | --- |
| Contract | The commercial agreement between you and one of your customers. Invoices, subscriptions, usage and credits all hang off a contract. |
| Invoice | An immutable, numbered billing document. Once issued it is never edited — corrections are separate credit-note documents. |
| Subscription | A recurring billing relationship on a contract: cadence, price, trial, pause and cancellation state. |
| Usage | Metered consumption aggregated per contract and billing period, with plan allowances and caps. |
| Credits | Stored-value balances (prepayments, promotional credit) and their append-only ledger. |

## Versioning

The path prefix (`/billing-api/v1`) is the API version. Backwards-compatible
additions (new fields, new endpoints) happen within a version; breaking
changes get a new prefix. Unknown response fields must be ignored by clients.

## Identifiers

Billing resources use numeric `id`s (`int64`), unique per resource type.
Contract, invoice, and subscription ids are safe to store and to use in URLs.
Your tenant identity is derived from the API key — it is never passed as a
parameter, and objects belonging to other sellers are indistinguishable from
missing ones (`404`).

## Immutability

Issued invoices are append-only legal records. There is no update or delete:
a wrong invoice is voided or corrected by a credit note, and both documents
remain visible in listings. Credit ledger entries are likewise append-only.

---

# Concepts

Five objects, and the relationships between them are not obvious from their
names. Read this once and the rest of the reference follows; skip it and the
most likely mistake is inventing a call that cannot exist.

```
                        ┌──────────────┐
                        │   Customer   │  who you bill
                        └──────┬───────┘
                               │ one customer, many contracts
                        ┌──────▼───────┐
                        │   Contract   │  the agreement: currency, term
                        └──────┬───────┘
              ┌────────────────┼────────────────┐
              │                │                │
     ┌────────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐
     │ Subscription  │  │    Usage    │  │   Credits   │
     │ recurring fee │  │ metered qty │  │ stored value│
     └────────┬──────┘  └──────┬──────┘  └──────┬──────┘
              │                │                │
              └───────┬────────┘                │ drawn down at issue
                      │ billed by a run          │
               ┌──────▼───────┐                  │
               │   Invoice    │◄─────────────────┘
               │  immutable   │
               └──────────────┘
```

**Contract is the anchor.** Everything else hangs off one. A subscription, a
usage meter, a credit balance and an invoice all name a contract, and the
contract carries the currency they must all agree on.

**Invoice is a document, not a record you edit.** Once issued it has a number
and is immutable. A correction is a new document — a credit note — and both
stay visible in every listing. There is no `PATCH` and no `DELETE`, which
means an agent cannot be told to "fix" an invoice: the only correct move is
to issue a correcting one.

## Three questions the object names do not answer

### Can an invoice exist without a contract?

**No.** Every invoice names a contract, and issuing one without it is refused
before anything is written.

**But you do not have to create the contract first.** An ad-hoc invoice — a
one-off with `origin: adhoc` — provisions what it needs from the bill-to you
type: the customer is found or created by email, and a live contract in the
same currency is reused if one exists, created if not. So a one-off stays one
call. Send the same recipient a second one-off and it lands on the same
customer and the same contract rather than minting duplicates.

This provisioning is deliberately **only** for ad-hoc documents. A usage or
recurring invoice with no contract is a caller mistake, and inventing a
contract for it would detach that revenue from the agreement it belongs to.

### Does a subscription generate invoices automatically?

**No — not by itself.** Two different mechanisms are easy to confuse:

- The **lifecycle pass** advances a subscription's *state* on its dates: a
  trial activates, a cancellation takes effect after its notice period, a
  fixed end expires it, and a term that has rolled over gets the term now in
  force. It issues no documents at all.
- The **billing run** raises the money. It bills each revenue model on a
  contract — recurring, then usage, then project work, then any one-time line
  — each through its own engine, each producing its own document so the
  invoice's `origin` stays truthful.

So a subscription's period turning over does not, on its own, produce an
invoice. Something has to run the billing — and on a seller who has the
issuance passes switched on (`billing.recurring.invoice_pass`,
`billing.usage.invoice_pass`), that something is a schedule, not a person.
Both default to off. Write your integration so a document appearing without
you is normal, not an anomaly.

**Double billing is prevented by claims, not by memory.** A subscription
period lands on a unique `(subscription, period_start)` row, usage lines and
project work flip guarded status columns, and every claim's invoice carries
its id. Re-running a billing run finishes only what is missing; an ambiguous
commit is repaired by looking the claim up, never by issuing again. A model
that fails does not roll back a sibling's document — a numbered invoice
cannot be un-issued — and the run reports per model what happened.

### Do credits apply before or after tax?

**After.** Credit is a payment method, not a discount. It draws down the
invoice's grand total — the amount *including* tax — and never reduces the
taxable base. The tax the document reports is the tax on the full price,
whatever the customer's balance was.

Two consequences worth knowing before you model this:

- A credit-funded invoice is neither *expected* nor *received* cash. It is its
  own thing, and reporting treats it that way.
- **An invoice collected by bank transfer draws no credit at all.** The buyer
  was told to wire the grand total; shrinking the collectible underneath that
  instruction would make every full-face wire arrive as an overpayment. The
  balance stays on the ledger for the next link-collected document.

## Three words that are one letter of confusion apart

The platform has three roles, and two of their field names differ by a single
word while meaning entirely different things:

The direction of the money is what separates them:

```
   Customer  ──── pays ────►   Seller   ──── pays ────►   Payee
 sellerCustomerId            sellerAccountId             payeeId
 your buyer                  YOU, the key holder         who you disburse to
 Billing API                 both APIs                   Payments API
```

| Word | Who | Lives on |
| --- | --- | --- |
| **Seller** (`sellerAccountId`) | **You** — the account holder the API key belongs to. Every object in both APIs is scoped to one. | Both APIs |
| **Customer** (`sellerCustomerId`) | Who **pays you** — the party your invoices are addressed to. | This API |
| **Payee** (`payeeId`) | Who **you pay** — a counterparty receiving money through split payments and payouts. | Payments API |

`sellerAccountId` and `sellerCustomerId` look like siblings and are not: the
first is your own identity, the second is your customer's. A marketplace
operator is all three sentences at once — they **are** a Fynex seller, they
**have** customers who pay invoices, and they **have** payees who receive
splits and payouts.

If you think in the words *vendor*, *merchant* or *supplier*: the merchant
running the account is the **seller**; a vendor or supplier you disburse money
to is a **payee**; the buyer you bill is a **customer**. The settlement-trail
endpoint (`GET /invoices/{invoiceId}/settlement`) is where the two APIs meet:
a customer's payment on this side becomes a payee's payout on the other.

## Where money and quantities live

| Thing | On the wire |
| --- | --- |
| An amount of money | Integer **minor units**, field ends `Minor` — `4999` is €49.99 |
| A rate or percentage | Integer **basis points**, field ends `Bps` — `275` is 2.75% |
| A metered quantity | Decimal **string** — `"1250.5"` |
| A per-unit rate | Decimal **string** in MAJOR units — `"0.004"`, the one deliberate exception, because a rate is routinely finer than a minor unit |

Everything on a contract shares that contract's currency. There is no
conversion anywhere in this API: a mismatch is refused rather than converted.

---

# Quickstart

This walks from a fresh API key to a working integration. Every example is
copy-pasteable; replace the key and ids with your own.

## 1. Get a key

In the Fynex dashboard, open **Integration** in the left-hand menu and issue a
**secret** key from the API keys card.

- `sk_test_…` — authenticates while your account is in demo mode.
- `sk_live_…` — authenticates once your account is live.

An account is in exactly one of those modes, so exactly one of the two key
environments works at any time.

Keys are stored only as hashes, so a key is shown once, at creation. If you
lose it, regenerate — there is no recovery. Keep keys server-side: they carry
full read access to your billing data.

## 2. Set your base URL

Every endpoint sits under the path `/billing-api/v1`. The host depends on the
environment you were onboarded to, so the examples below use a variable:

```bash
export FYNEX_API_BASE="https://staging-api.fynex.ai/billing-api/v1"
export FYNEX_API_KEY="sk_test_4f6f..."
```

| Environment | Host |
| --- | --- |
| Staging | `https://staging-api.fynex.ai` |
| Production | Confirm your production host with Fynex before going live — it is assigned per deployment, and a `sk_live_` key is only accepted by the environment that issued it. |

You are reading these docs on the same host the API runs on, so
`/billing-api/v1/openapi.json` and `/billing-api/v1/docs` are always
reachable relative to wherever this page is served.

## 3. Make your first call

`GET /contracts` is the safest first request — it needs no ids and tells you
whether your key, environment, and network path all work:

```bash
curl -s $FYNEX_API_BASE/contracts \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

```json
{
  "contracts": [
    {
      "contractId": 42,
      "contractNumber": "UK2607AA",
      "version": 1,
      "sellerCustomerId": 7,
      "currency": "EUR",
      "status": "active",
      "startDate": "2026-01-01",
      "customerName": "Ada Lovelace",
      "customerCompanyName": "Harbour Group BV"
    }
  ]
}
```

`contractId` is the key to every per-contract endpoint that follows.

If instead you get:

- `401` — the header is missing or the key is wrong. The format is
  `Authorization: Bearer sk_live_…`; a bare key without `Bearer ` fails.
- `403` — the key is valid but the seller account is not active. Check the
  account status in the dashboard.
- an empty `contracts` array — the key works, but this account has no
  contracts yet.

## 4. List invoices

```bash
curl -s "$FYNEX_API_BASE/invoices?limit=5" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

```json
{
  "invoices": [
    {
      "id": 4180,
      "contractId": 42,
      "sellerCustomerId": 7,
      "origin": "usage",
      "invoiceNumber": "UK2607AA-2608AAB",
      "jurisdiction": "UK",
      "invoiceType": "standard",
      "status": "sent",
      "currency": "EUR",
      "issueDate": "2026-08-01T00:00:00Z",
      "dueDate": "2026-08-15T00:00:00Z",
      "subtotalMinor": 10000,
      "taxTotalMinor": 2000,
      "grandTotalMinor": 12000,
      "creditAppliedMinor": 0,
      "collectibleMinor": 12000,
      "creditSettledMinor": 0,
      "reverseCharge": false,
      "paymentLinkId": 991
    }
  ],
  "hasMore": true,
  "nextCursor": 4180,
  "nextBeforeId": 4180
}
```

Two things to internalize right now, because they cause most integration
bugs:

- **Amounts are integers in minor units.** `12000` in EUR is €120.00. Never
  parse them as floats.
- **`grandTotalMinor` is the document total, `collectibleMinor` is what
  collection asks the customer for.** They differ when stored credit funded
  part of the invoice. Neither drops to zero once the invoice is paid — to
  decide "does this customer still owe us money", read `status`.
- **`creditSettledMinor` is not a payment total.** It counts only stored
  credit drawn down, so a card-paid invoice reports `0` there.

## 5. Get one invoice with its lines

```bash
curl -s $FYNEX_API_BASE/invoices/4180 \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

```json
{
  "invoice": { "id": 4180, "invoiceNumber": "UK2607AA-2608AAB", "...": "..." },
  "lines": [
    {
      "position": 1,
      "description": "API calls over allowance",
      "quantity": "250",
      "unitPriceMinor": 40,
      "discountMinor": 0,
      "netAmountMinor": 10000,
      "taxCategory": "standard",
      "taxRate": "20",
      "taxAmountMinor": 2000,
      "sourceRef": "usage:api_calls:2026-07"
    }
  ]
}
```

`quantity` and `taxRate` are decimal **strings** — they carry fractional
precision that a JSON number would round. Feed them to a decimal type, not a
float.

## 6. Download the PDF

```bash
curl -s $FYNEX_API_BASE/invoices/4180/pdf \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -o invoice-UK2607AA-2608AAB.pdf
```

The response is `application/pdf` bytes with a `Content-Disposition`
filename. It renders from the document's frozen payload, so a PDF fetched
today and one fetched next year are identical.

## Next

- **Workflows** shows the end-to-end recipes: collecting on an invoice,
  reconciling a month, watching usage against limits.
- **Pagination & Amounts** covers the paging loop you will need past 20 rows.
- **Errors** covers the status contract, rate limits, and retry policy.

---

# Authentication

Every Billing API request must carry a seller secret key:

```
Authorization: Bearer sk_live_4f6f...
```

Keys come in two environments, and the environment must match your account's
current mode: a Fynex seller account operates either in demo mode or live
mode, never both at once. While the account is in demo mode only `sk_test_…`
keys authenticate; after go-live only `sk_live_…` keys do, and the old test
key answers `401` from then on. There is no second, parallel dataset behind
the two prefixes — the API always returns your account's own billing records.

Keys are issued and rotated in the Fynex dashboard, on the **Integration**
page, and
are stored server-side only as SHA-256 hashes; a lost key cannot be recovered,
only regenerated.

Only `sk_test_…` and `sk_live_…` secret keys authenticate this public API.
Publishable `pk_…` keys, dashboard sessions, legacy seller tokens, cookies and
query-string credentials are rejected. This is a server-to-server API: never
call it from a browser or mobile app, and rotate or revoke a compromised key
in the dashboard immediately. No Billing-specific token store or session is
created; authorization reuses the existing hashed API-key record and its
active/revoked and environment checks.

Failure contract:

- `401` — the header is missing, malformed, or the key is unknown or revoked.
- `403` — the key is valid but the seller account is not active.

The seller account behind the key is the authoritative tenant: every object
this API returns belongs to that seller, and ids belonging to another tenant
answer `404`. Never embed secret keys in client-side code; calls must
originate from your servers.

---

# Sandbox & testing

Everything here works without touching live money. The goal: your first
successful call within minutes, and a full trial-to-renewal subscription
exercised without waiting a month of wall-clock time.

## Hosts

| Environment | Host |
| --- | --- |
| Staging | `https://staging-api.fynex.ai` |
| Production | Assigned per deployment — confirm yours with Fynex before go-live. |

The environment that matters is your **account's**, not the host's: a Fynex
account operates in demo mode or live mode, and test behaviour follows the
account. Demo accounts exist on both hosts.

Both hosts are also declared in the OpenAPI document itself, in its `servers`
block — production first, the sandbox second, each labelled. A generated client
or an agent that reads only the spec can therefore pick the sandbox rather than
defaulting to the one host it happens to see. Each entry is the bare origin;
the `/billing-api/v1` prefix is already part of every path in the document, so
join a server with a path exactly as written and do not add the prefix twice.

## Keys

**No account yet? Mint a sandbox in one call.** `POST /sandbox/accounts` with
a JSON body creates an anonymous demo seller — wallets, a demo terminal, a
pre-set split rule, three test customers — and returns its `sk_test_` key:

```bash
curl -X POST https://staging-api.fynex.ai/sandbox/accounts \
  -H "Content-Type: application/json" -d '{}'
```

The door is open on the sandbox host (`staging-api.fynex.ai`); a host that has
it switched off answers `503` to this call and shows no `/sandbox` page. The
secret is shown once; the keys are time-limited — `expiresAt` in the
response says exactly when they stop working. An anonymous sandbox has no
dashboard login — it is a key, not a user — and it is a test environment: never
enter real personal or bank details. The `/sandbox` page on the API host has
the full contract.

For your own account, issue a **secret** key in the Fynex dashboard: **Integration** in the
left-hand menu, then the API keys card. While your account is in demo mode the
key is `sk_test_…`; after go-live only `sk_live_…` keys authenticate and the
test key answers `401` from then on. A key is shown once, at creation — store
it server-side and never in a browser.

The same key authenticates every surface in these docs: the Billing API and
usage ingestion under `/billing-api/v1`, and the Payments API.

## Test cards

On a demo account, hosted payment pages (including the links
`POST /invoices/{invoiceId}/send` creates) accept these Visa sandbox numbers:

| Card number | Notes |
| --- | --- |
| `4111 1111 1111 1111` | Universal Visa test card |
| `4530 9100 0001 2345` | Visa |
| `4037 1122 3300 0001` | Visa |

For all of them: any future expiry, any 3-digit CVV, Latin cardholder name.
Paying an invoice's link with one of these drives the document through
`sent → paid` exactly as a live card would, so it is the way to test the
settlement-polling loop end to end.

## Time travel

Subscription flows — trial ending, first charge, renewal — run on billing
dates, and a sandbox that makes you wait 30 real days for a renewal is not a
sandbox. **Each contract can be given a test clock of its own and moved
forward**, with a `sk_test_` key and no help from us:

| Call | What it does |
| --- | --- |
| `GET /contracts/{contractId}/test-clock` | Reads what the billing engines treat as *now* for that one contract. |
| `POST /contracts/{contractId}/test-clock/advance` | Moves it forward to `to`, then runs that contract's subscription lifecycle and recurring invoicing as of it. |

**Test-mode (demo) accounts only.** A live account answers `403` on both: a
live subscription's renewal is real revenue and a real document to a real
customer.

**One contract at a time.** The clock belongs to the contract in the path.
Advancing it never moves a sibling contract — yours or another account's — and
no scheduled pass sees a changed clock. That is why this is safe to publish.

**Forward only, capped at 366 days.** `to` must be after the contract's
current clock. Re-sending the instant the clock already sits at is a **no-op**:
`200` with `advanced: false`, nothing renewed and nothing issued twice, so the
call is safe to retry. A target in the past is `400` — the invoices an advance
mints are numbered and immutable, so a clock cannot be wound back.

### Worked example: a monthly subscription renewing in one call

Create the subscription today (`42` is a contract that already carries at
least one invoice — see the note below):

```bash
curl -s -X POST "$FYNEX_API_BASE/contracts/42/subscriptions" \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"frequency":"monthly","priceMinor":4999,"currency":"EUR","startDate":"2026-01-01"}'
```

Ask where the contract's clock is:

```bash
curl -s "$FYNEX_API_BASE/contracts/42/test-clock" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
# {"contractId":42,"now":"2026-01-01T09:15:00Z","simulated":false}
```

Advance it past the end of the first term — 31 days:

```bash
curl -s -X POST "$FYNEX_API_BASE/contracts/42/test-clock/advance" \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"2026-02-01T00:00:00Z"}'
```

```json
{
  "clock": { "contractId": 42, "now": "2026-02-01T00:00:00Z", "simulated": true },
  "advanced": true,
  "lifecycle": { "renewed": 1, "trialsActivated": 0, "cronDisabled": false },
  "invoices": { "issued": 1, "sent": 1, "skipped": 0, "failed": 0, "passDisabled": false }
}
```

The renewal is now visible on the two reads that matter — the subscription's
new term, and the document it earned:

```bash
curl -s "$FYNEX_API_BASE/subscriptions?contractId=42" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
# currentPeriodStart moves to 2026-02-01, currentPeriodEnd to 2026-03-01

curl -s "$FYNEX_API_BASE/invoices?contractId=42" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
# one more invoice, origin "recurring", for the new term
```

`GET /contracts/{contractId}/invoices/upcoming` before the advance, and the
issued document after it, should agree — which is the cheapest end-to-end
check that your contract is configured the way you think it is.

### What it does not advance

The clock moves the **subscription state machine** and the **recurring
invoice**. It does *not*:

- close metered usage periods or mint usage invoices,
- send dunning e-mail for a subscription that went `past_due`,
- run off-session auto-charge on an issued invoice,
- move the issue date: an invoice raised by an advance is dated at REAL time
  (so its number stays in the real month's gapless sequence) while its period
  is the simulated term — read the period, not the date, to check the renewal.

Those stay on real time in their own scheduled passes, and every advance
repeats the list in its `notAdvanced` field. Do not write a test that waits on
one of them after an advance.

### When an advance renews but issues nothing

Two operator switches decide whether the halves above run at all, and the
response says which one stopped:

| Response field | Switch | Symptom |
| --- | --- | --- |
| `lifecycle.cronDisabled` | `billing.subscription.lifecycle_cron` | Nothing renews, no matter how far the clock moves. |
| `invoices.passDisabled` | `billing.recurring.invoice_pass` | The term renews, and no document appears on `GET /invoices`. |

Both default to **off** — see the table below. There is also one data
precondition the clock cannot supply: the recurring lane continues a
contract's existing invoicing pattern, so a contract with **no prior invoice**
is reported in `invoices.skipped` rather than issued. Raise the first document
once with `POST /invoices` (or let a contract you already invoiced carry the
subscription), and every later advance issues by itself.

The staff-operated clock is a different thing and is not this. It shifts the
lifecycle dates of test-mode *payment-link* subscriptions (the recurring
hosted-checkout product), estate-wide, and never touches the billing
subscriptions this reference describes.

## What a fresh sandbox has switched off

Several billing capabilities sit behind operator feature flags that default to
**off**, because each one moves money or issues documents on a schedule. A
sandbox where they are off looks broken — subscriptions never charge, usage
periods never close into invoices, no invoice is ever raised, credits report
`501` — when it is merely unconfigured. If a flow below does nothing, ask Fynex
to confirm the flag before debugging your integration:

| Flag | What it gates |
| --- | --- |
| `billing.subscription.lifecycle_cron` | The pass that ends trials, charges renewals and applies scheduled plan changes. |
| `billing.usage.close_pass` | The pass that closes usage periods and mints usage invoice lines. |
| `billing.recurring.invoice_pass` | The pass that turns due subscription terms into issued invoices. |
| `billing.usage.invoice_pass` | The pass that composes closed usage lines into issued invoices. Separate from the recurring one on purpose — a seller may be ready to auto-bill terms and not metered usage, or the reverse. |
| `billing.proration.invoice_binding` | Whether a subscription's unbilled mid-term proration is put on the invoice its term is billed on — a charge as an extra line, a credit as a discount on the recurring line, any remainder as a non-expiring `proration` credit lot. While off, a mid-term change is still recorded against the contract but never reaches a document. |
| `billing.invoice.auto_charge` | Off-session collection: the loop that charges a customer's saved card for a sent or overdue invoice. Without it a document is only ever paid by someone visiting its link or making a transfer. |
| `payment_links.recurring_billing` | Recurring charging through hosted payment links. |
| `billing.credits` | Stored-value credits; while off, the credit endpoints answer `501` and invoices draw no credit down. |

**Closing a period is not the same as billing it.** The close pass and the
invoice passes are different switches: with only `billing.usage.close_pass` on,
`GET /contracts/{contractId}/usage` moves and periods close, and no invoice
ever appears on `GET /invoices`. That pairing is the single most common reason
a sandbox looks like it has stopped halfway.

## A sandbox session that proves the loop

The target this page is written against is the one in our own onboarding
PRD: **a first transaction under 30 minutes, self-serve** — from a fresh
sandbox key to an invoice on `GET /invoices` without talking to anyone at
Fynex. The steps below are that path; if one of them cannot be done inside
that budget, the gap is ours, not yours.

1. `GET /contracts` — key, host and network path all work.
2. Register a metric and price it (see **Usage ingestion**), send a few
   events, and watch `GET /contracts/{contractId}/usage` move.
3. Create a subscription in the dashboard with a trial that has already
   ended, and let the lifecycle pass run — the renewal invoice appears on
   `GET /invoices`.
4. `POST /invoices/{invoiceId}/send`, pay the link with a test card, and poll
   the invoice to `paid`.

That is the whole billing loop — metering, rating, issuance, collection,
settlement — without a real card or a real month.

---

# Errors

Errors are JSON with a single field:

```json
{"error": "invoice not found"}
```

(Authentication failures from the gateway layer may answer with a plain-text
body; treat any non-2xx as failed regardless of body shape.)

Every response, including `401`, `429`, and server errors, carries
`X-Request-Id: req_<uuid>`. Include this value in a support request; it is the
safe correlation handle for a request, not your API key or customer data.

| Status | Meaning |
| --- | --- |
| `400` | The request is malformed: an unparseable id, an unknown filter value, an invalid parameter. |
| `401` | Missing or invalid API key. |
| `403` | The key is valid but the seller account is not active. |
| `404` | The object does not exist — or belongs to another seller. |
| `422` | The object exists but the action is not applicable to it (for example, sending an invoice that is collected by bank transfer). |
| `429` | Rate limit exceeded. Honour `Retry-After` and the `X-RateLimit-*` headers. |
| `501` | The capability is not enabled for this deployment (for example, credits before stored value is switched on). |
| `500` | Server fault. Safe to retry idempotent (GET) requests with backoff. |

## Rate limiting

Requests are rate-limited per seller, on a budget dedicated to this API —
billing traffic and payments-api traffic do not throttle each other. The
default budget is **1000 requests per hour per seller**, with a burst of 100 so
a single client cannot spend the whole hour in one instant. The number is set
per environment, so read `X-RateLimit-Limit` rather than hard-coding it.

Responses normally carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and
`X-RateLimit-Reset` (whole seconds until the budget refills), plus the current
standards-track structured fields `RateLimit-Policy` (`"seller";q=1000;qu="requests";w=3600`)
and `RateLimit` (`"seller";r=940;t=2100`). Both spellings carry the same numbers.
Note these are not the `RateLimit-Limit`/`RateLimit-Remaining`/`RateLimit-Reset`
triple from an earlier revision of that draft, which is not sent. Read them rather than
assuming a number: the budget is set per environment, and `X-RateLimit-Limit`
is the authoritative value for yours. Treat them as advisory — during a limiter outage requests are allowed through without the
headers, so a client that requires them will break exactly when the platform
is already degraded.

Three write operations carry an **extra** per-seller quota on top of that
budget, each in its own bucket, because each accepted call spends something
that cannot be handed back:

| Operation | Default quota | Why |
| --- | --- | --- |
| `POST /contracts` | 20 requests per rolling 24 hours (refusals and replays count) | Bounds how fast one key opens contracts; a create allocates a number from a series shared across sellers. |
| `POST /contracts/{contractId}/amendments` | 200 requests per rolling 24 hours (a stale `expectedBaseVersion` counts) | Every accepted amendment appends a contract version — up to 100 line items — to a history that is append-only and has no delete. |
| `POST /invoices` | 500 requests per rolling 24 hours (refusals and replays count) | Issuing allocates a number from your own gapless series, so a runaway loop burns your month of numbers. |

All three refuse with the same `429`, `Retry-After` and `X-RateLimit-*`
headers as the surface-wide limit.

A rejected request answers `429` with `Retry-After` in seconds. Wait that
long — retrying sooner only deepens the overage.

Bulk work is what actually hits this. Reconciling a month walks pages of up
to 100 invoices and may pull a PDF per document, so a few hundred requests in
one burst is normal. Pace bulk exports (a short sleep between pages costs far
less than being throttled mid-walk), and if a legitimate workload cannot fit
the budget, ask Fynex to raise it rather than working around it with parallel
keys.

### When the write quotas fail closed

Unlike the surface-wide budget, those three operations — `POST /contracts`,
`POST /contracts/{contractId}/amendments` and `POST /invoices` — **fail
closed**. While the limiter itself is unreachable they answer `503` with
`Retry-After` instead of letting an uncounted burst of writes through. Nothing
was created, amended or issued, so the retry is safe: wait the header out and
repeat the call with the **same `Idempotency-Key`**, which is what stops the
retry from opening a second contract or issuing a second document. Amendments
carry no `Idempotency-Key` — resend the same `expectedBaseVersion`, and a
version that did land answers `422` rather than appending a duplicate.

Two things this does *not* mean. It is the limiter FAILING, not the quota
being absent: a deployment that switches a quota off (its request budget set
to `0`) is simply unmetered on that operation, exactly as before, and never
answers `503` for this reason. And the quotas count **requests**, not
successes — a refusal or a replay spends one too, so a client retrying a `400`
in a loop can exhaust its day without ever writing anything.

---

# Pagination

Every list endpoint pages by keyset, with the same two parameters:

- `limit` — page size, 1–100 (default 20).
- `cursor` — where to continue from. Omit it (or pass `0`) for the first page.

Each page reports how to continue:

```json
{
  "invoices": [ ... ],
  "hasMore": true,
  "nextCursor": 4177
}
```

Pass `nextCursor` back as `cursor` until `hasMore` is `false`. That loop is
the same code on every list in this API.

Keyset paging is stable under concurrent inserts: new rows appear on the first
page of a fresh iteration and never shift the pages of an iteration already in
flight.

## Direction is a property of the list, not of the parameter

The lists do not all walk the same way, and that part is deliberate:

| List | Order | A cursor means |
| --- | --- | --- |
| `/invoices`, `/subscriptions` | Newest first | ids **below** the cursor |
| The credit ledger on `/contracts/{contractId}/credits` | Newest first | ids **below** the cursor |
| `/contracts` | Ascending contract id | ids **above** the cursor |

Contracts walk forward because the id is a stable identity to iterate, not a
recency ranking. What used to differ as well was the parameter NAME —
`beforeId` on some lists, `afterId` on others — so anyone who wrote a working
loop for invoices wrote a broken one for contracts. `cursor` and `nextCursor`
are the same on all of them; only the documented order changes.

The credit ledger pages the `entries` array only: the balances in the same
response are always complete. Seller-wide credit balances are one row per
currency and credit type, so that list is genuinely bounded and does not page.

## The original parameter names

`beforeId` / `nextBeforeId` and `afterId` / `nextAfterId` still work,
unchanged, on the lists that had them, and every response still carries the
original field beside `nextCursor` with the same value. Existing integrations
need no change. Sending both `cursor` and the original name with **different**
values is a `400` rather than a silent choice between them.

## Dates

`issuedFrom` and `issuedTo` accept a calendar date (`2026-08-01`) or a full
RFC 3339 timestamp. A bare date is read as **UTC midnight**, and the range is
half-open — `issuedFrom` inclusive, `issuedTo` exclusive — so adjacent months
never double-count a document. If your books close in a non-UTC zone, send the
timestamp form with your offset rather than the bare date.

## Amounts

All monetary amounts are **integers in the currency's minor units**
(`grandTotalMinor: 12050` is €120.50 for a EUR document). Quantities and tax
rates are decimal strings. Never parse amounts as floating point.

---

# Endpoint reference

Every operation, with its exact parameters, response shape and failure modes.
Every one requires `Authorization: Bearer sk_live_…` (or `sk_test_…`); all
amounts are integers in minor units; all list responses page.

Base: `$FYNEX_API_BASE` = `https://<your-host>/billing-api/v1`

## How numbers ride on the wire

One rule, four rows, and the field name tells you which row applies. Read the
suffix before you read the value.

| Value | Type | Field name | Example |
| --- | --- | --- | --- |
| Money amount | Integer, **minor units** | ends `Minor` | `4999` is €49.99 |
| Rate / percentage | Integer, **basis points** | ends `Bps` | `275` is 2.75% |
| Quantity | Decimal **string** | — | `"1250.5"` |
| Tax rate | Decimal **string**, percent | — | `"20.0"` |

Money is never a float and never a decimal string: a `…Minor` field is an
integer count of the currency's smallest unit, paired with the resource's ISO
4217 `currency`. Reading `4999` as euros overstates the amount a hundredfold,
and reading `275` as a percentage does the same to a rate — which is why the
unit is repeated in every field's own description rather than stated once here.

Quantities go the other way and travel as strings on purpose: metered
consumption is routinely finer than an integer, and JSON numbers are IEEE
floats. Per-unit **rates** are the one deliberate exception to minor units —
they are decimal strings in major units, because a rate is often smaller than
one minor unit (`"0.004"`).

The convention is enforced, not merely documented: a `…Minor` or `…Bps` field
that publishes as a float, or whose description never names its unit, fails the
build.

| | Operation | Purpose |
| --- | --- | --- |
| 1 | `GET /contracts` | The entry point — ids for every per-contract read |
| 1a | `POST /contracts` | Create a contract (`Idempotency-Key` required; extra per-seller quota) |
| 1b | `POST /contracts/{contractId}/amendments` | Append a contract version — status, dates, components, counterparty (extra per-seller quota) |
| 2 | `GET /contracts/{contractId}/usage` | Metered consumption this period |
| 3 | `GET /contracts/{contractId}/credits` | One contract's stored value + ledger |
| 4 | `GET /credits` | Stored-value balances across all contracts |
| 4a | `POST /contracts/{contractId}/credits/top-up` | Grant credit on a contract (`Idempotency-Key` required) |
| 5 | `GET /invoices` | Invoice list, filtered and paged |
| 5a | `POST /invoices` | Compose and issue an invoice (`Idempotency-Key` required; extra per-seller quota) |
| 6 | `GET /invoices/{invoiceId}` | One invoice with its lines |
| 7 | `GET /invoices/{invoiceId}/pdf` | The rendered document |
| 8 | `POST /invoices/{invoiceId}/send` | Create the payment link (emails the customer) |
| 9 | `GET /subscriptions` | Subscription list |
| 10 | `GET /subscriptions/{subscriptionId}` | One subscription |
| 10a | `POST /contracts/{contractId}/subscriptions` | Create a subscription (`Idempotency-Key` required) |
| 10b | `POST /subscriptions/{subscriptionId}/cancel` · `/pause` · `/resume` · `/end-trial` · `/change-plan` | Drive a subscription's lifecycle |
| 11 | `POST /usage/events` · `:batch` | Report metered consumption |
| 12 | `GET`/`POST /usage/metrics` · `GET /usage/metrics/{metricName}` | The meter registry |
| 13 | `PUT`/`GET /usage/contracts/{contractId}/metrics/{metricName}/price` | Price a metric on a contract |
| 14 | `POST /prices/evaluate` | Preview what a config charges — the billing engine, pure |
| 15 | `POST /usage/csv` | Bulk intake from a periodic export |
| 18 | `GET /invoices/export` | A period's invoices as one CSV/NDJSON file — month-end, without the paging loop |
| 19 | `GET /invoices/{invoiceId}/settlement` | Which payments and payouts settled this invoice |
| 20 | `POST /customers` | Create or resolve a customer — the `sellerCustomerId` everything else needs |
| 21 | `GET /contracts/{contractId}/invoices/upcoming` | What the contract's next invoice would carry — an estimate, nothing written |
| 16 | `GET /usage/dead-letters` · `{deadLetterId}/redrive` · `{deadLetterId}/discard` | Events an intake refused, and what to do with them |
| 17 | `GET`/`POST /usage/webhook-endpoints` · `{endpointId}/rotate-secret` · `{endpointId}/revoke` | Inbound webhook endpoints and their signing secrets |

---

## 1. `GET /contracts`

Lists the contracts your key can see. Every per-contract endpoint takes an id
from here.

| Parameter | In | Default | Notes |
| --- | --- | --- | --- |
| `cursor` | query | — | Keyset cursor. Only contracts with an id **above** this value — this list walks forward. Omit for the first page; pass back the `nextCursor` of the previous page. |
| `afterId` | query | — | The original name of `cursor` on this list. Still accepted and identical; sending both with different values is a `400`. |
| `limit` | query | `20` | 1–100. |

Contracts page **forward** (ascending id) because the id is a stable identity
to walk, not a recency ranking. Invoices, subscriptions and the credit ledger
page **backward** (newest first) — see the Pagination reference
(`billing-pagination.md`), which also states the keyset stability guarantee
and the amounts convention.

```bash
curl -s "$FYNEX_API_BASE/contracts?limit=50" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

```json
{
  "contracts": [
    {
      "contractId": 42,
      "contractNumber": "UK2607AA",
      "version": 1,
      "sellerCustomerId": 7,
      "currency": "EUR",
      "status": "active",
      "startDate": "2026-01-01",
      "endDate": "2026-12-31",
      "customerName": "Ada Lovelace",
      "customerPhone": "+31 6 1234 5678",
      "customerCompanyName": "Harbour Group BV",
      "customerCompanyCountry": "NL"
    }
  ],
  "hasMore": true,
  "nextCursor": 42,
  "nextAfterId": 42
}
```

| Field | Meaning |
| --- | --- |
| `contractId` | The key for endpoints 2 and 3. |
| `contractNumber` | Document number (`UK2607AA`). Empty for contracts predating numbering. |
| `version` | Contract version; you always get the current one. |
| `sellerCustomerId` | Your customer on this contract. Also an invoice filter. |
| `currency` | Contract currency (ISO 4217). |
| `status` | Contract lifecycle state, e.g. `active`. |
| `startDate` / `endDate` | `YYYY-MM-DD`. `endDate` absent on open-ended contracts. |
| `customerName` / `customerPhone` | The customer's name and phone as agreed on the contract. Absent when not stated. |
| `customerCompanyName` / `customerCompanyCountry` | The customer's company and its registration country as agreed on the contract. Absent when not stated. |

**Failures:** `400` malformed `cursor`/`afterId`/`limit`, or both cursor names sent with different values · `401` bad key · `403`
inactive seller.

---

## 1a. `POST /contracts`

Creates a contract, in `draft`, for one of your customers. The contract is the
anchor every other object refers to — subscriptions, credit, metered prices and
invoices — and it bills in one currency for its whole life.

**`Idempotency-Key` is a required header**: 1–128 characters from
`A–Z a–z 0–9 _ . : -`, one per contract you intend to create. Keys are scoped to
your seller account. Keys beginning with a prefix the billing engine uses for its own ledger rows (`proration:`, `proration-grant:`, `redeem:`, `subscription:`, `credit_note:`, `refund:`, `usage-adjustment:`) are refused with `400` — they are not yours to use. The same key returns the contract the first call created
(its *current* version) and answers `200` instead of `201`. **The body is
compared**, in two halves.

`sellerCustomerId` and `currency` are compared against the contract's current
version — neither is amendable, so the two versions agree. Everything an
amendment *can* move is compared against **version 1**, the version this key
actually created, so a contract that was legitimately re-dated or re-priced
does not turn every later retry into a refusal:

- `startDate` and `endDate`, present or absent;
- `lineItems` **line by line** — `componentType`, `componentConfig` and
  `quantity` — and in any order, not merely how many there are. Two components
  of the same type at different quantities are two different contracts, and a
  count alone answered the second with the first;
- `customerName`, `customerPhone`, `customerCompanyName` and
  `customerCompanyCountry`, each compared *only when your request states it* —
  a blank one is inherited from the customer record, which is exactly what the
  first call did.

A difference in any of them answers `422` naming the field.

```bash
curl -s -X POST "$FYNEX_API_BASE/contracts" \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Idempotency-Key: 5c2f7c40-1a3e-4c9b-9d1f-2b6e5a0c7d31" \
  -H "Content-Type: application/json" \
  -d '{
    "sellerCustomerId": 7,
    "currency": "EUR",
    "startDate": "2026-10-01"
  }'
```

| Field | Notes |
| --- | --- |
| `sellerCustomerId` | Required; one of your customers (endpoint 20). Another seller's id is `400`. |
| `currency` | Required. ISO 4217, one of `EUR`, `USD`, `GBP`, `DKK`, `NOK`, `SEK`. Immutable: every subscription, credit lot and invoice under the contract must use it. |
| `startDate` | Required. `YYYY-MM-DD`, up to a year in the past and ten years ahead; the window is measured in whole days. |
| `endDate` | Optional `YYYY-MM-DD`; omit for open-ended. Not before `startDate`, and not more than ten years ahead. |
| `lineItems` | Optional components, at most 100: `componentType` (`recurring`, `usage`, `one_time`, `milestone`, `project`, `marketplace`, `credit`, `adjustment`, `hybrid`), `quantity` (decimal string), `componentConfig` (JSON the engine reads for that type, at most 16 KiB). There is no `priceRef`, and a `componentConfig` carrying `milestoneDefinitionRef`, `projectRef` or `splitRuleRef` is `400` — those name objects this API does not publish. Omit for a contract billed only by its subscriptions and metered prices. |
| `customerName` / `customerPhone` / `customerCompanyName` / `customerCompanyCountry` | The counterparty's details *as agreed on this contract*; blank ones default from the customer record. 128 / 32 / 255 / 56 characters. |

Answers the same contract shape endpoint 1 lists — `id`, `version` (`1`),
`status` (`draft`), `currency`, `startDate`, `endDate`, `contractNumber` when
numbering is enabled.

**Failures:** `400` (a missing `sellerCustomerId`, `currency` or `startDate`,
unknown currency, malformed date, a date outside the window, over-long detail,
an unavailable `componentConfig` reference, a `sellerCustomerId` that is not
yours — the same answer whether it is another seller's or no customer at all —
missing or malformed `Idempotency-Key`) ·
`422` (`Idempotency-Key` already used for a different contract) · `429` ·
`503` · `401` / `403`.

`429` here has **two** ceilings behind it. The surface-wide per-seller rate
limit applies as everywhere else, and creating a contract carries an *extra*
per-seller quota of its own — **20 create requests per rolling 24 hours** by default — requests, not contracts: a refused or replayed call counts too.
That quota bounds how fast one key can open contracts; the budget above is
sized for bulk reads. It is deliberately not a guarantee about the shared
`CC+YYMM` number namespace, which 20 a day could not give: contract numbering
is a rollout switch that is off by default, and where it is on the allocator
fails the create rather than reusing a number. Both ceilings answer `429` with
`Retry-After`; an integration that opens contracts as customers sign up will
never see either.

The quota fails closed — **`503`** with `Retry-After` while its limiter is
unreachable, and nothing was created. See [Errors → rate limiting](/billing-api/v1/docs/errors#when-the-write-quotas-fail-closed).

---

## 1b. `POST /contracts/{contractId}/amendments`

Appends a **version** to a contract you own. Nothing on a contract is edited
in place: a status move, new dates, a replaced component set or a corrected
counterparty detail is a new version, and every earlier one stays readable.

`expectedBaseVersion` is the concurrency guard — send the `version` you last
read. If the contract has moved on since, the amendment answers `422`; re-read
and decide again. There is no `Idempotency-Key`: a repeat of a successful
amendment fails the version check by construction.

```bash
curl -s -X POST "$FYNEX_API_BASE/contracts/42/amendments" \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedBaseVersion": 1, "status": "active"}'
```

| Field | Notes |
| --- | --- |
| `expectedBaseVersion` | Required, positive: the version you last read. |
| `status` | `draft`, `active`, `suspended` or `closed`; omit to keep. Illegal transitions (anything out of `closed`, `draft` straight to `suspended`) are `422`. |
| `startDate` / `endDate` | `YYYY-MM-DD`; omit to keep. An existing end date cannot yet be cleared. |
| `lineItems` | Omit to carry the current set forward; send the full new set to replace it; `[]` clears it. At most 100. |
| `customerName` / `customerPhone` / `customerCompanyName` / `customerCompanyCountry` | Send to replace, omit to keep, `""` to clear. |

Answers the new version (`version` is `expectedBaseVersion + 1`) in the same
contract shape as endpoint 1.

**Failures:** `400` (malformed field, unknown `status`) · `404` (contract is
not yours) · `422` (stale `expectedBaseVersion`, closed contract, illegal
status transition) · `429` · `503` · `401` / `403`.

`429` here has **two** ceilings behind it, as on endpoint 1a. The surface-wide
per-seller rate limit applies as everywhere else, and amending carries an
*extra* per-seller quota of its own — **200 amend requests per rolling 24 hours** (a stale `expectedBaseVersion` counts too)
by default — because every accepted amendment appends a version, with up to
100 line items, to a history that is append-only and has no delete. Like the
create quota it fails closed — **`503`** with `Retry-After` while its limiter
is unreachable, and nothing was appended. See [Errors → rate limiting](/billing-api/v1/docs/errors#when-the-write-quotas-fail-closed).

---

## 2. `GET /contracts/{contractId}/usage`

The contract's **current open** billing periods, one entry per metric. This is
a live read, not a closed-period figure — reconcile money against invoices.

```bash
curl -s "$FYNEX_API_BASE/contracts/42/usage" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

```json
{
  "contractId": 42,
  "metrics": [
    {
      "metricName": "api_calls",
      "used": "10250",
      "includedUnits": "10000",
      "capQuantity": "50000",
      "capMode": "hard",
      "percentOfCap": "20.5",
      "percentOfPlan": "102.5",
      "periodStart": "2026-08-01",
      "periodEnd": "2026-08-31"
    }
  ]
}
```

| Field | Meaning |
| --- | --- |
| `used` | Metered so far this period. Decimal **string**. |
| `includedUnits` | Plan allowance for the period. |
| `capQuantity` / `capMode` | The ceiling and how it is enforced: `hard` blocks past it, `soft` only alerts. Absent when no limit policy exists. |
| `percentOfPlan` | Above `100` means overage — what will be rated onto the next usage invoice. |
| `percentOfCap` | Distance to the enforcement ceiling. Warn customers well before `100`. |
| `periodStart` / `periodEnd` | Open period bounds. Absent when a metric has a policy but no usage yet. |

**Failures:** `400` non-numeric id · `404` unknown contract, or one belonging
to another seller (the two are indistinguishable by design).

A real contract with nothing metered answers `200` with `"metrics": []` — a
valid state, not an error.

---

## 3. `GET /contracts/{contractId}/credits`

One contract's stored-value balances plus a page of its append-only ledger.

| Parameter | In | Default | Notes |
| --- | --- | --- | --- |
| `contractId` | path | — | Required. |
| `cursor` | query | — | Keyset cursor over the ledger: entries with an id **below** this value. Pass back the previous page's `nextCursor`. |
| `beforeId` | query | — | The original name of `cursor` on this list. Still accepted and identical; sending both with different values is a `400`. |
| `limit` | query | `20` | 1–100. Applies to `entries` only — `balances` is always complete. |

```bash
curl -s "$FYNEX_API_BASE/contracts/42/credits?limit=50" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

```json
{
  "balances": [
    {"currency": "EUR", "creditType": "purchased", "balanceMinor": 250000, "isLiability": true}
  ],
  "entries": [
    {
      "id": 1201,
      "sellerCustomerId": 7,
      "kind": "topup",
      "creditType": "purchased",
      "signedDeltaMinor": 250000,
      "currency": "EUR",
      "lotId": 900,
      "invoiceId": null,
      "expiresAt": null,
      "reason": "annual prepayment",
      "occurredAt": "2026-08-01T09:30:00Z"
    }
  ],
  "hasMore": true,
  "nextCursor": 1201,
  "nextBeforeId": 1201
}
```

| Field | Meaning |
| --- | --- |
| `kind` | `topup` (granted or bought), `deduction` (consumed into an invoice), `expiry` (a lapsed lot removed). |
| `signedDeltaMinor` | Positive for `topup`, negative for the other two. |
| `lotId` | The grant a deduction or expiry consumed. |
| `invoiceId` | The invoice a deduction funded — the link back to the document. |
| `isLiability` | True for **paid-for** types (`purchased`, `enterprise`, `proration`): unearned revenue you owe as service. Granted credit is not a liability, and only granted credit can expire. |

**Failures:** `400` bad id or paging · `404` unknown/foreign contract ·
`501` stored value is not enabled for this deployment.

Replaying the ledger from the beginning always reproduces the balance:
corrections are new rows, never edits.

---

## 4. `GET /credits`

Your stored-value position across every contract, one row per currency and
credit type. Bounded, so it does not page.

```bash
curl -s "$FYNEX_API_BASE/credits" -H "Authorization: Bearer $FYNEX_API_KEY"
```

```json
{
  "balances": [
    {"currency": "EUR", "creditType": "purchased", "balanceMinor": 250000, "isLiability": true},
    {"currency": "EUR", "creditType": "promotional", "balanceMinor": 5000, "isLiability": false}
  ]
}
```

Credit types: `promotional`, `purchased`, `manual`, `gift`, `enterprise`,
`ai_token`, `marketplace`, `proration`. `proration` is minted only by the
billing engine (unserved time returned on a mid-term downgrade) and cannot be
granted by hand. Finance usually wants liabilities separated from granted
credit — do not sum them blindly.

**Failures:** `401` · `403` · `501` (capability off).

---

## 4a. `POST /contracts/{contractId}/credits/top-up`

Grants a credit **lot** on a contract you own — prepaid balance the invoice
engine draws down before any payment rail is asked for money. The ledger is
append-only, and this is the only way credit enters it: the deductions,
expiries and reversals that take it out are the engine's own rows and have no
public route.

**`Idempotency-Key` is a required header**: 1–128 characters from
`A–Z a–z 0–9 _ . : -`, one per grant you intend to make. Keys are scoped to
your seller account. The same key returns the grant the first call created and
answers `200` instead of `201`. Keys beginning with a prefix the billing engine uses for its own ledger rows (`proration:`, `proration-grant:`, `redeem:`, `subscription:`, `credit_note:`, `refund:`, `usage-adjustment:`) are refused with `400` — they are not yours to use. The engine's own
`proration-grant:` lots live in the same index, and the recurring lane adopts
the lot it finds under that key as the term's grant — which is exactly why no
caller may put one there.

Unlike the subscription create, **the body is compared**, and what is compared
is everything about the lot you decide: `contractId`, `amountMinor`,
`currency`, `creditType`, `expiresAt` (present or absent), `sellerCustomerId`
and `reason`. A difference in any of them answers `422` naming the field rather
than handing back the earlier grant: a top-up has a natural shape, and silently
returning the first one would hide a second grant that never happened.
Normalisation is not a difference — casing on `currency` and `creditType`, and
surrounding whitespace on `reason`, replay as the same grant.

```bash
curl -s -X POST "$FYNEX_API_BASE/contracts/42/credits/top-up" \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Idempotency-Key: 3f0b6a1e-9c1d-4f10-9f2b-6f2a1c1e6a1e" \
  -H "Content-Type: application/json" \
  -d '{
    "creditType": "purchased",
    "amountMinor": 250000,
    "currency": "EUR",
    "reason": "annual prepayment"
  }'
```

| Field | Notes |
| --- | --- |
| `creditType` | `promotional`, `purchased`, `manual`, `gift`, `enterprise`, `ai_token` or `marketplace`. `purchased` and `enterprise` were PAID FOR — they are a liability you owe as service. |
| `amountMinor` | The lot, in **minor units**, 1 to 10^12. Always positive: this is the grant, not a movement. |
| `currency` | ISO 4217, and it must equal the contract's current currency — credit is never converted. A different one is `400`. |
| `expiresAt` | RFC 3339 instant the lot lapses; omit for credit that never expires. Must be in the future, and is refused outright on `purchased` and `enterprise` credit — money someone paid must not evaporate on a calendar date. |
| `reason` | Required, at most 512 characters. Recorded on the ledger row. |
| `sellerCustomerId` | Optional attribution for per-customer reporting; must be one of your customers (endpoint 20). The contract is still the balance anchor. |

Answers the same `CreditLedgerEntry` shape endpoint 3 lists — `id`, `kind`
(`topup`), `creditType`, `signedDeltaMinor`, `currency`, `lotId`, `expiresAt`,
`reason`, `occurredAt`. A top-up **is** a lot, so `lotId` is absent on it; the
deductions that later consume it name this entry's `id`.

**Failures:** `400` (unknown `creditType`, `amountMinor` outside the range, a
`currency` other than the contract's, a `reason` over 512 characters, a
`sellerCustomerId` that is not yours, missing or malformed `Idempotency-Key`) ·
`404` (contract is not yours) · `422` (`Idempotency-Key` already used for a
different grant) · `429` · `401` / `403` · `501` (capability off).

---

## 5. `GET /invoices`

The workhorse. Newest first, keyset paged, with filters that let you fetch a
bounded slice instead of walking history.

| Parameter | In | Default | Notes |
| --- | --- | --- | --- |
| `contractId` | query | — | One contract. |
| `sellerCustomerId` | query | — | One of your customers, across contracts. |
| `origin` | query | — | `recurring`, `usage`, `milestone`, `project`, `one_time`, `adhoc`, `marketplace`. `subscription` is a deprecated alias of `recurring` and resolves to the same set. |
| `status` | query | — | `draft`, `issued`, `sent`, `paid`, `overdue`, `voided`, `written_off`. |
| `invoiceType` | query | — | `standard`, `credit_note`, `simplified`, `modified`. |
| `corrects` | query | — | Credit notes issued against this invoice **number**. |
| `issuedFrom` | query | — | Inclusive lower bound. `YYYY-MM-DD` (UTC midnight) or RFC 3339. |
| `issuedTo` | query | — | **Exclusive** upper bound, so adjacent periods never double-count. |
| `cursor` | query | — | Keyset cursor: rows with an id **below** this value — this list walks backward. Pass back the previous page's `nextCursor`. |
| `beforeId` | query | — | The original name of `cursor` on this list. Still accepted and identical; sending both with different values is a `400`. |
| `limit` | query | `20` | 1–100. |

`origin`, `status` and `invoiceType` reject an unrecognized value with `400`,
so a typo cannot masquerade as "no such invoices". `contractId`,
`sellerCustomerId` and `corrects` are matched as given — a well-formed but
wrong value legitimately returns an empty page.

```bash
curl -s "$FYNEX_API_BASE/invoices?issuedFrom=2026-08-01&issuedTo=2026-09-01&status=sent&limit=100" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

```json
{
  "invoices": [
    {
      "id": 4180,
      "contractId": 42,
      "sellerCustomerId": 7,
      "origin": "usage",
      "invoiceNumber": "UK2607AA-2608AAB",
      "jurisdiction": "UK",
      "invoiceType": "standard",
      "status": "sent",
      "currency": "EUR",
      "issueDate": "2026-08-01T00:00:00Z",
      "dueDate": "2026-08-15T00:00:00Z",
      "subtotalMinor": 10000,
      "taxTotalMinor": 2000,
      "grandTotalMinor": 12000,
      "creditAppliedMinor": 0,
      "collectibleMinor": 12000,
      "creditSettledMinor": 0,
      "outstandingMinor": 12000,
      "reverseCharge": false,
      "paymentLinkId": 991
    }
  ],
  "hasMore": true,
  "nextCursor": 4180,
  "nextBeforeId": 4180
}
```

List rows omit `customerName` / `customerEmail` — those live in the frozen
payload and reading them per row would mean parsing every document. Use
`sellerCustomerId` to group, or fetch the single invoice (endpoint 6).

**Failures:** `400` unknown enum value, malformed date or paging · `401` ·
`403`.

---

## 5a. `POST /invoices`

Composes, numbers and — unless `send` is `false` — sends an invoice in one
call. The document is **issued the moment this answers `201`**: numbered
gaplessly under your agreement, its totals recomputed server-side, its payload
frozen. There are no drafts on this API and no edits afterwards.

**Credit notes are not issued here.** A correction is raised *against* the
document it corrects — it mirrors that document's lines and retires its payment
link — none of which can be reconstructed from a hand-composed body, so
`invoiceType: credit_note` is `400` and there is no `originalInvoiceNumber`
field on this request. Corrections are made in the dashboard.

**`Idempotency-Key` is a required header**, same shape as endpoint 1a. The same
key returns the document the first call issued and answers `200` — with no
`paymentLinkUrl` and no `deliveryStatus`, because delivery is not replayed.
**The body is compared**, and what is compared is everything that decides
*which* document this is:

- `contractId`, `sellerCustomerId`, `currency`, `invoiceType`, `jurisdiction`;
- `dueDate` and `dateOfSupply`, present or absent, and an `exemptionReason` or
  `legalNotice` your request states (an omitted one is the engine's to decide —
  it supplies its own on an exempt or reverse-charge document — and it decides
  the same way twice);
- the document's own text: `notes`, `poReference`, `paymentTerms`;
- the whole `buyer` block as it was frozen onto the document — the same money
  addressed to somebody else is a different legal record — and the `seller`
  block *as the engine used it*: under Fynex-collection issuance the issuer is
  substituted for the one you sent, so a retry that states a different seller
  still replays;
- the net total of the lines before tax (`quantity × unitPriceMinor −
  discountMinor`, summed), how many lines there are, and **each line's
  `description`, `quantity` and `unitPriceMinor`** — two lines whose net
  happens to match (`2 × 5000` and `4 × 2500`) are still different lines;
- **each line's `discountMinor`, `taxCategory`, `taxRatePercent` and
  `taxable`** — these decide the TAX on a line whose net amount is identical,
  which the net total above cannot see, so a retry that drops `taxRatePercent`
  from `20` to `0` is a different document, not a replay.

A difference in any of them answers `422` naming the field, and no second
document is numbered.

`send` is deliberately **not** compared: it chooses whether to deliver the
document, not what the document says, so a retry that flips it still replays.

```bash
curl -s -X POST "$FYNEX_API_BASE/invoices" \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Idempotency-Key: 8d1e4b2a-6f3c-4e7a-9b0d-1c2e3f4a5b6c" \
  -H "Content-Type: application/json" \
  -d '{
    "contractId": 42,
    "sellerCustomerId": 7,
    "jurisdiction": "UK",
    "currency": "EUR",
    "dueDate": "2026-11-01",
    "buyer": {"name": "Ada Lovelace", "email": "ada@example.com", "addressLine1": "1 Analytical Row", "city": "London", "postalCode": "E1 6AN", "country": "GB"},
    "lineItems": [{"description": "Seats, October", "quantity": "10", "unitPriceMinor": 4999, "taxCategory": "standard", "taxRatePercent": "20"}]
  }'
```

| Field | Notes |
| --- | --- |
| `contractId` / `sellerCustomerId` | Both required and both yours (endpoints 1a and 20). Nothing is provisioned here: an unknown contract is `404`, a foreign customer `400`. |
| `jurisdiction` | Required; which tax regime the document is composed under. Exactly `UK`, `US` or `EU` — the input is upper-cased first, so `uk` is accepted and stored as `UK`. |
| `invoiceType` | `standard` (default), `simplified` (only below the jurisdiction's retail threshold) or `modified` (UK retail above it, VAT-inclusive line prices). `credit_note` is refused with `400`. |
| `currency` | Must equal the contract's — a different one is `400`. |
| `dueDate` / `dateOfSupply` | `YYYY-MM-DD`. |
| `buyer` | The addressee: `name`, `email`, `addressLine1`, `city`, `postalCode`, `country` required — `email` is where the document is delivered, and a request without one is `400`; `phone`, `addressLine2`, `region`, `businessType`, `vatNumber`, `companyRegistrationNumber`, `taxExemptionCertificateNumber`, `ein`, `salesTaxId` optional. |
| `seller` | Optional. Ignored under Fynex-collection issuance, where Fynex is the issuing party; used as the issuing identity only for a merchant-issued seller. |
| `lineItems` | 1–200 lines: `description`, `quantity` (decimal string), `unitPriceMinor` (required, integer minor units), `discountMinor`, `taxCategory`, `taxRatePercent` (decimal string, 0–100), `taxable`, `sourceRef`. A UK/EU line must carry a `taxCategory` (`standard`, `reduced`, `zero`, `exempt`) and its rate must agree with it; a US line carries `taxable` and no category. No `catalogItemId` — send explicit prices. |
| `poReference` / `notes` / `paymentTerms` / `exemptionReason` / `legalNotice` | Free text, 128 / 2000 / 256 / 64 / 2000 characters. |
| `send` | Default `true`: create the hosted payment link and e-mail the buyer. `false` issues without delivering; `POST /invoices/{invoiceId}/send` delivers later. |

Answers `{"invoice": …, "paymentLinkUrl": …, "deliveryStatus": …}` — the same
invoice shape endpoint 6 returns, plus the link when one was created. **A
delivery failure does not undo issuance**: the answer is still `201` with the
document and no link.

`deliveryStatus` says what *this* call's delivery attempt did, because an
absent `paymentLinkUrl` alone cannot tell three different situations apart —
and only one of them is yours to act on:

| Value | Meaning |
| --- | --- |
| `sent` | The collection link was created and e-mailed; `paymentLinkUrl` carries it. |
| `not_requested` | No delivery was attempted: `send` was `false`, or the document was settled from stored credit at issue and has nothing left to collect. Nothing is wrong. |
| `failed` | The document **is** issued and immutable, and delivery did not happen. Retry it with `POST /invoices/{invoiceId}/send`, which tells you why (a test-mode recipient the sandbox rule refuses is the usual reason). |

The field is absent on an idempotent replay, which attempts no delivery of its
own and must not restate the first call's outcome.

**Failures:** `400` (input the engine refuses, `invoiceType: credit_note`, a
missing `buyer.email`, a `currency` other than the contract's, a foreign
`sellerCustomerId`, missing or malformed `Idempotency-Key`)
· `404` (contract is not yours) · `422` (`Idempotency-Key` already used for a
different document; a merchant-issued `seller` block missing the legal name,
address or tax details a compliant document needs — the detail names the
fields; a UK/EU exemption without the issuer's VAT number) · `429` · `503` ·
`401` / `403`. The incomplete-issuer case answered `400` before 2026-09; it is
a state of the seller's profile, not of the request, so it now sits with the
other `422`s.

`429` here has **two** ceilings behind it, as on endpoint 1a. The surface-wide
per-seller rate limit applies as everywhere else, and issuing carries an
*extra* per-seller quota of its own — **500 issue requests per rolling 24 hours** (refusals and replays count too) by
default. It is far larger than the contract create's on purpose: issuing
allocates a gapless number from *your own* `AGREEMENT-YYMM` series
(the `AAA…ZZZ` order suffix within it), so a runaway integration burns a month
of your numbers rather than a namespace shared with other sellers. Both answer
`429` with `Retry-After` and the `X-RateLimit-*` headers.

The quota fails closed — **`503`** with `Retry-After` while its limiter is
unreachable, and nothing was issued. See [Errors → rate limiting](/billing-api/v1/docs/errors#when-the-write-quotas-fail-closed).

---

## 6. `GET /invoices/{invoiceId}`

One invoice, its lines, and the customer identity as recorded at issue.

```bash
curl -s "$FYNEX_API_BASE/invoices/4180" -H "Authorization: Bearer $FYNEX_API_KEY"
```

```json
{
  "invoice": {
    "id": 4180,
    "customerName": "Acme GmbH",
    "customerEmail": "ap@acme.example",
    "invoiceNumber": "UK2607AA-2608AAB",
    "status": "sent",
    "grandTotalMinor": 12000,
    "collectibleMinor": 12000,
    "creditSettledMinor": 0,
    "outstandingMinor": 12000,
    "paidVia": "",
    "…": "every field from the list shape"
  },
  "lines": [
    {
      "position": 1,
      "description": "API calls over allowance",
      "quantity": "250",
      "unitPriceMinor": 40,
      "discountMinor": 0,
      "netAmountMinor": 10000,
      "taxCategory": "standard",
      "taxRate": "20",
      "taxAmountMinor": 2000,
      "sourceRef": "usage:api_calls:2026-07"
    }
  ]
}
```

### The four money fields, precisely

| Field | Is | Is **not** |
| --- | --- | --- |
| `grandTotalMinor` | The legal document total | |
| `collectibleMinor` | What collection asks the customer for — grand total less credit applied at issue | A balance. It does **not** drop to zero when paid, and it is blind to later credit notes, write-offs and adjustments. |
| `creditSettledMinor` | The part discharged by stored credit | A payment total. A card-paid invoice reports `0`. |
| `outstandingMinor` | The receivable: the document total plus every adjustment ledger entry against it, less what has been settled. A voided document reports `0`. This is the figure to age in an AR report. | Guaranteed present. It is omitted when the adjustment ledger is unavailable — treat its absence as **unknown**, never as `0`. |

"Has this been paid?" is answered by `status` (and `paidVia` for how), never
by arithmetic on the amounts.

`collectibleMinor` and `outstandingMinor` agree on a document nothing has
happened to. They diverge the moment one does: credit-note a `12000` invoice by
`5000` and `collectibleMinor` still reads `12000` while `outstandingMinor` reads
`7000`. Ageing `collectibleMinor` over-states receivables.

`customerName` / `customerEmail` are who the document was addressed to **at
issue** — a customer renaming themselves later does not rewrite an issued
legal record. Empty when the payload carries no buyer. (The contract list's
`customerName` is different: it is the currently agreed value on the
contract, not a frozen document field.)

### Correction and tax fields

Present only when they apply, so treat every one as optional.

| Field | Meaning |
| --- | --- |
| `originalInvoiceNumber` | On a credit note: the invoice number it corrects. Find corrections the other way round with `?corrects=`. |
| `voidedAt` / `voidReason` | The document was cancelled before money moved. The invoice is not deleted — an issued invoice is a legal record — so this is a status plus an audited reason. |
| `writtenOffAt` / `writeOffReason` | Collection was abandoned. Kept separate from the void fields so the two corrections stay distinguishable. |
| `dateOfSupply` | The tax point, when it differs from `issueDate`. |
| `reverseCharge` | True when the reverse-charge mechanism applies — the buyer accounts for the VAT. |
| `exemptionReason` | Exemption code, when the document is exempt. |
| `legalNotice` | Jurisdiction-mandated text printed on the document. |
| `paidVia` | How a paid document settled: `payment_link`, `bank_transfer`, or `credit` (stored credit covered it in full). |
| `paymentLinkId` | The collection link, once sent. Use the URL from `POST …/send`, not this id. |

On a line, `taxable` is the US-jurisdiction flag; UK/EU documents use
`taxCategory` and `taxRate` instead.

**Failures:** `400` non-numeric id · `404` unknown or foreign invoice.

---

## 7. `GET /invoices/{invoiceId}/pdf`

The rendered document, `application/pdf`, with a `Content-Disposition`
filename derived from the invoice number.

```bash
curl -s "$FYNEX_API_BASE/invoices/4180/pdf" \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -o UK2607AA-2608AAB.pdf
```

Rendered from the frozen payload, so the same invoice produces the same
document today and next year. Every issued document renders — including
voided ones and credit notes, which are part of the audit trail.

Rendering is the most expensive operation here; when bulk-downloading, pace
the loop (see Errors → rate limiting).

**Failures:** `400` · `404` · `500` if the stored payload no longer validates
(a server-side integrity fault; retrying will not fix it).

---

## 8. `POST /invoices/{invoiceId}/send`

Materializes the collection instrument: creates the invoice's hosted payment
link and returns its URL.

> **This emails your customer.** Whenever the document carries a buyer email,
> the first call delivers the payment invitation. There is no per-request
> suppression in v1, so do not call it merely to obtain a URL for internal
> use — the first call is customer-facing and cannot be undone.

```bash
curl -s -X POST "$FYNEX_API_BASE/invoices/4180/send" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

```json
{
  "invoice": { "id": 4180, "status": "sent", "paymentLinkId": 991, "…": "…" },
  "paymentLinkUrl": "https://pay.example-host/p/7bc1f2a9e4d5"
}
```

**Repeat calls are safe, including concurrently, and take no idempotency
header.** The invoice id is itself the collection anchor: a unique
payment-link association makes concurrent calls converge on one link.
Repeating a successful call returns that same link and does not send another
email.

Use the returned URL — never construct one. The hosted host is per-deployment
configuration.

`422` cases, none retryable without a state change:

| Message | Meaning |
| --- | --- |
| `invoice is collected by bank transfer and cannot create a payment link` | The document instructs a wire to a named account; a simultaneously payable card link could let both succeed. |
| `invoice has nothing left to collect` | Zero total, or stored credit covers it. |
| `invoice is not in a sendable state` | `draft`, or already `paid`, `voided` or `written_off`. A settled invoice never hands out a payment link. |
| `payment-link: sandbox emails can only go to *@sandbox.fynex.ai, *@example.test, or your own verified email` | The seller is in test mode and the invoice's customer address is neither a reserved test domain nor an address the seller itself owns. Test mode never e-mails a real customer. |

**Failures:** `400` · `404` · `422` (above) · `401` / `403`.

---

## 9. `GET /subscriptions`

| Parameter | In | Default | Notes |
| --- | --- | --- | --- |
| `contractId` | query | — | One contract. |
| `cursor` | query | — | Keyset cursor, newest first: rows with an id **below** this value. Pass back the previous page's `nextCursor`. |
| `beforeId` | query | — | The original name of `cursor` on this list. Still accepted and identical; sending both with different values is a `400`. |
| `limit` | query | `20` | 1–100. |

```bash
curl -s "$FYNEX_API_BASE/subscriptions?contractId=42" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

```json
{
  "subscriptions": [
    {
      "id": 310,
      "contractId": 42,
      "status": "active",
      "billingFrequency": "monthly",
      "priceMinor": 9900,
      "currency": "EUR",
      "anchorDate": "2026-01-01T00:00:00Z",
      "startDate": "2026-01-01T00:00:00Z",
      "currentPeriodStart": "2026-08-01T00:00:00Z",
      "currentPeriodEnd": "2026-08-31T00:00:00Z",
      "autoRenew": true,
      "prorationPolicy": "by_day",
      "noticePeriodDays": 0,
      "trialRequiresPaymentMethod": false,
      "createdAt": "2026-01-01T09:00:00Z",
      "updatedAt": "2026-08-01T00:05:00Z"
    }
  ],
  "hasMore": false
}
```

---

## 10. `GET /subscriptions/{subscriptionId}`

Same shape, one record. `subscriptionId` is the path parameter; ids come from
endpoint 9.

### Cadence fields

`billingFrequency` is one of `daily`, `weekly`, `bi_weekly`, `monthly`,
`quarterly`, `semi_annual`, `annual` or `custom`. The annual cadence is named
`annual` — there is no yearly value, so a branch written against one never
fires. On a custom cadence, `customUnit` (`day`, `week`, `month`, `year`) and
`customEvery` (the multiplier) describe the repeat: `customUnit: "week"` with
`customEvery: 2` bills fortnightly. Both are absent on the named frequencies.

### Reading a subscription correctly

| Question | Read |
| --- | --- |
| What are they paying? | `priceMinor` + `currency` + `billingFrequency`. There is no separate plan object — those three fields *are* the plan. |
| Is a change coming? | `pendingPriceMinor` / `pendingPriceChangeAt`. Showing only `priceMinor` misinforms a customer who already requested a downgrade. |
| Are they leaving? | `cancelRequestedAt` / `cancelEffectiveAt`. Service continues until the effective date, so `status` alone is not the answer. |
| Are they paying yet? | `status: "trial"` plus `trialEnd`. `trialEndBehavior` says which way it ends — `convert` or `cancel` — and `trialRequiresPaymentMethod` whether a method must be on file first. |
| Did a charge fail? | `status: "past_due"`. **Nothing retries it automatically** — this is a queue for you to work. |
| Paused? | `pausedAt`, with `pauseEndsAt` for a scheduled auto-resume. |
| What proration was agreed? | `prorationPolicy` — `by_day`, `full_period` or `next_period`; absent when never stated. It **selects what an immediate `change-plan` does while the proration engine is enabled** for the platform: `by_day` (and an unstated term) puts the new price in force today and posts an adjustment for the unserved remainder, `full_period` puts the new price in force today and bills the **whole** current period at it — the days already elapsed included — posting no adjustment, `next_period` keeps the old price for the rest of the current period and applies the new one from the next. The engine is **off by default**, and while it is off no adjustment is posted and a mid-cycle change lands immediately whatever this says — so read it as the contract's written intent until an operator turns proration on. Where invoice binding is enabled for the environment as well, the posted adjustment reaches the term's next invoice as a line, a discount, or a `proration` credit lot. |

States: `trial` → `active` ⇄ `past_due` / `paused` → `canceled` | `expired`.

**Failures:** `400` · `404`.

---

## 10a. `POST /contracts/{contractId}/subscriptions`

Creates a subscription on a contract you own. `contractId` is the path
parameter; the body is the plan and the term. **`Idempotency-Key` is a
required header**: 1–128 characters from `A–Z a–z 0–9 _ . : -`, one per
subscription you intend to create — a UUID is the usual choice. Keys are
scoped to your seller account, not to the contract. Keys beginning with a prefix the billing engine uses for its own ledger rows (`proration:`, `proration-grant:`, `redeem:`, `subscription:`, `credit_note:`, `refund:`, `usage-adjustment:`) are refused with `400` — they are not yours to use. The same key always
returns the subscription the first call created and answers `200` instead of
`201`; the body of a retry is not compared. A key replayed against a
*different* contract answers `422` rather than returning the other contract's
subscription. Two concurrent first calls with one key produce one
subscription, which both callers receive.

```bash
curl -s -X POST "$FYNEX_API_BASE/contracts/42/subscriptions" \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Idempotency-Key: 9c1d0b3a-7e55-4f10-9f2b-6f2a1c1e6a1e" \
  -H "Content-Type: application/json" \
  -d '{
    "frequency": "monthly",
    "priceMinor": 9900,
    "currency": "EUR",
    "startDate": "2026-10-01",
    "trialEnd": "2026-10-15",
    "trialEndBehavior": "convert",
    "noticePeriodDays": 30,
    "prorationPolicy": "by_day"
  }'
```

| Field | Notes |
| --- | --- |
| `frequency` | `daily`, `weekly`, `bi_weekly`, `monthly`, `quarterly`, `semi_annual`, `annual` or `custom`. `custom` needs `customUnit` (`day`/`week`/`month`/`year`) and `customEvery`. |
| `priceMinor`, `currency` | The plan: one full period's charge in minor units (1 to 10^12), in the contract's currency. Immutable currency. |
| `startDate`, `anchorDate` | `YYYY-MM-DD`. `anchorDate` defaults to `trialEnd` for a trial, `startDate` otherwise. A past `startDate` — up to a year back — is caught up by the next lifecycle pass. |
| `trialEnd`, `trialEndBehavior`, `trialRequiresPaymentMethod` | A future `trialEnd` starts the subscription in `trial`; `convert` (default) or `cancel` decides how it ends. |
| `autoRenew`, `endDate` | `autoRenew` defaults to `true`. `false` fixes the term and requires `endDate`; `endDate` with `autoRenew` true is refused. |
| `noticePeriodDays` | Notice a cancellation requires, 0–365; `0` cancels at the current term's end. |
| `prorationPolicy` | `by_day`, `full_period` or `next_period`. Selects what an immediate `change-plan` does once the proration engine is enabled — prorate the remainder, bill the whole current period at the new price (elapsed days included, no adjustment), or hold the old price until the next period. Inert while the engine is off (the default); where invoice binding is enabled as well, the posted adjustment is applied to the term's next invoice. |

Answers the same `Subscription` shape as endpoint 10. **Failures:** `400` (input
outside the ranges above, a `currency` other than the contract's, missing or
malformed `Idempotency-Key`) · `404` (contract is not yours) · `422`
(`Idempotency-Key` already used on another contract) · `429` · `401` / `403`.

## 10b. Lifecycle actions

All `POST`, all on `/subscriptions/{subscriptionId}/…`, all returning the
updated subscription. A request the current state cannot take answers `422`
with the reason — pausing a trial, resuming an active subscription,
cancelling twice — and so does a lost race against the lifecycle pass
(`subscription changed concurrently; re-read it and retry`). `404` means the
subscription is not yours.

| Path | Body | From | Effect |
| --- | --- | --- | --- |
| `/subscriptions/{subscriptionId}/cancel` | — | `trial`, `active`, `past_due`, `paused` | `cancelRequestedAt` set; serves until `cancelEffectiveAt` (notice) or term end. Terminal. |
| `/subscriptions/{subscriptionId}/pause` | `{"pauseUntil": "YYYY-MM-DD"}` optional | `active` | Billing suspended; `pauseEndsAt` when a date was given. Beyond the seller's pause policy → `422`. |
| `/subscriptions/{subscriptionId}/resume` | — | `paused` | New term from today; the pause is not billed. |
| `/subscriptions/{subscriptionId}/end-trial` | — | `trial` | Converts now, per `trialEndBehavior` and `trialRequiresPaymentMethod`. |
| `/subscriptions/{subscriptionId}/change-plan` | `{"priceMinor": 12900, "currency": "EUR", "atTermEnd": true}` | `active` | `atTermEnd: true` schedules (`pendingPriceMinor`) and is always honoured; `false` leaves the timing to the subscription's `prorationPolicy` (`next_period` holds the old price until the next period, anything else applies the new one now — see the policy table above). Same price, or a change already pending → `422`. The currency cannot change — a different one is `400`. |

Marking a subscription past-due or recovered has no public route: that is the
collection loop's verdict, not the integrator's.

---

## 11–13. The metered-usage write surface

Registering a metric (`name`, `unit`, `aggregation`), pricing it on a
contract (`contractId`, `metricName` path parameters; the config carries the
scheme, tiers, allotment and commitment), and reporting events
(`POST /usage/events`, one event; `POST /usage/events:batch`, many;
`quantity` as a decimal string, `occurredAt`, `idempotencyKey`) are
documented end to end in the **Usage ingestion** guide — parameters, the four
pricing schemes, the `metered: false` trap, and the failure table. The
operations live in this spec; the guide is their reference.

## 14. `POST /prices/evaluate`

Previews what a pricing configuration charges — through the same engine that
bills, so the number matches the invoice to the cent. Pure: nothing is
stored, no contract is referenced, and the config in the request is the same
document `PUT /usage/contracts/{contractId}/metrics/{metricName}/price`
stores.

```bash
curl -s -X POST "$FYNEX_API_BASE/prices/evaluate" \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "scheme": "graduated", "currency": "EUR", "rounding": "half_up",
      "unitPrice": "0",
      "tiers": [
        {"upTo": "10000", "unitPrice": "0.01", "flatAmount": "0"},
        {"upTo": null,    "unitPrice": "0.005", "flatAmount": "0"}
      ]
    },
    "quantities": ["12000"]
  }'
```

```json
{
  "results": [{
    "quantity": "12000",
    "amountMinor": 11000,
    "ratedAmountMinor": 11000,
    "currency": "EUR",
    "billableUnits": "12000",
    "includedUnitsApplied": "0",
    "carryOver": "0",
    "usageCapApplied": false,
    "spendCapApplied": false,
    "minimumApplied": false,
    "lines": [
      {"tierIndex": 0, "units": "10000", "unitPrice": "0.01", "flatAmount": "0", "amount": "100"},
      {"tierIndex": 1, "units": "2000", "unitPrice": "0.005", "flatAmount": "0", "amount": "10"}
    ]
  }]
}
```

Send several `quantities` (up to 100) to plot a price curve in one call;
`carriedOverUnits` seeds a rollover carry so the preview shows an existing
contract's next period. `amountMinor` is the money after the usage cap, spend
cap and minimum — the flags say which of them acted. Lines are exact decimals
in **major** units and always sum to the rated amount.

**Failures:** `400` — a malformed config or quantity, with the engine's own
validation message · `401` · `403`.

## 15. `POST /usage/csv`

Bulk intake for a periodic export. `multipart/form-data` with two parts.

| Part | Notes |
| --- | --- |
| `file` | The CSV itself. Without an idempotency-key column, keys derive from the file digest and line number — so re-uploading the same file is a no-op, not a double charge. |
| `mapping` | A `CSVMapping` JSON object naming which column carries which field. |

`quantityColumn` is required. Contract, metric and occurred-at may each come
from a column (`contractIdColumn`, `metricColumn`, `occurredAtColumn`) **or**
from a whole-file default (`defaultContractId`, `defaultMetric`,
`defaultOccurredAt`) — one or the other, never both for the same field.
`idempotencyKeyColumn` is optional.

```json
{"defaultContractId":42,"defaultMetric":"api_calls","quantityColumn":"calls","occurredAtColumn":"day"}
```

**Returns** `{"ingested":498,"duplicates":0,"deadLettered":2}`.

A row the pipeline refuses is dead-lettered rather than failing the upload, so
a partial success is normal — **read `deadLettered` on every response.** A file
that answers `200` with rows in the queue is not a file that billed.

**Failures:** `400` — not multipart, a mapping that is not exactly one
`CSVMapping` object, or a file-level rejection · `401` · `403` · `413` — the
file is over the per-call limit; split it.

---

## 16. `GET /usage/dead-letters`

Events an intake refused, newest first, each with the reason and the payload as
submitted. This is the queue to watch: a `2xx` from an intake does not mean
every row inside it was accepted.

| Field | Notes |
| --- | --- |
| `id` | Use it to redrive or discard. |
| `source` | Which intake produced it: `events`, `batch`, `csv`, `feed`, `webhook`. |
| `reason` | Why it was refused, in the intake's words. Fix this before redriving. |
| `status` | `pending`, `redriven` or `discarded`. Only `pending` can be acted on. |
| `attempts` | How many redrives have been tried. |
| `receivedAt` | RFC 3339. |
| `payload` | The event as submitted, so it can be corrected and resent. |

**Failures:** `401` · `403`.

### `POST /usage/dead-letters/{deadLetterId}/redrive`

`deadLetterId` is the `id` from the listing above. Resubmits the stored payload. Returns `{"status":"ingested","eventId":91424}`,
or `{"status":"rejected"}` when it fails again — the letter stays `pending`,
its `reason` is updated and `attempts` increments. Fix the cause first; a
redrive with the same problem fails the same way.

**Failures:** `401` · `403` · `404` — unknown id, or one belonging to another
seller.

### `POST /usage/dead-letters/{deadLetterId}/discard`

`deadLetterId` is the `id` from the listing above. Closes the letter without metering it, for a row that should never have been
sent. Returns `{"status":"discarded"}`. **Not reversible** — the usage it
described will not be billed.

**Failures:** `401` · `403` · `404`.

---

## 17. `POST /usage/webhook-endpoints`

Registers an endpoint your own system posts usage to, and mints the secret that
signs those deliveries.

**Body:** `{"description":"billing events → ERP staging"}` — optional, your own
label.

**Returns** `201` with the endpoint, the `secret`, and a `secretNote` restating
the terms:

```json
{"endpoint":{"id":12,"token":"whk_7f21c0","status":"active","createdAt":"2026-09-14T10:22:31Z"},
 "secret":"whsec_9c2f…","secretNote":"Copy this secret now: …"}
```

**The secret is in this response and nowhere else.** It is stored encrypted and
no endpoint reads it back. Copy it now; if it is lost, rotate.

The `token` is the path segment your sender posts to —
`POST /usage/v1/webhooks/{token}`. It is not a credential on its own: the HMAC
signature is what authenticates a delivery. That receiver stays on the
`/usage/v1` prefix deliberately and is not part of this key-authed surface,
because its signature covers the body and the body must be read before the
sender is known.

**Failures:** `400` · `401` · `403`.

### `GET /usage/webhook-endpoints`

Every endpoint you registered, revoked ones included. Secrets are never in a
listing.

**Failures:** `401` · `403`.

### `POST /usage/webhook-endpoints/{endpointId}/rotate-secret`

`endpointId` is the endpoint's `id`. Issues a new secret and returns it once, on the same display-once terms as
creation. **The old secret stops verifying immediately** — cut the sender over
in the same change, or deliveries fail in between.

**Failures:** `401` · `403` · `404`.

### `POST /usage/webhook-endpoints/{endpointId}/revoke`

`endpointId` is the endpoint's `id`. Closes the endpoint: deliveries to its token are refused from here on. Not
reversible — register a new endpoint instead. The record stays in the listing
so the history remains readable.

**Failures:** `401` · `403` · `404`.

---

## 18. `GET /invoices/export`

The month-end pull: every invoice issued in the window, as one file, so
reconciliation does not start with writing a paging loop.

| Parameter | In | Notes |
| --- | --- | --- |
| `issuedFrom` | query | **Required.** Start of the period, inclusive (`YYYY-MM-DD` or RFC 3339). |
| `issuedTo` | query | **Required.** End of the period, exclusive — adjacent months never double-count a document. |
| `format` | query | `csv` (default) or `ndjson`. |
| `contractId`, `origin`, `status`, `invoiceType` | query | The list's filters, same names, same validation. |

Both dates are required on purpose: there is no default window, because "the
file I exported" must never silently mean a window the server chose. An
inverted or empty range is rejected.

**CSV** carries one row per invoice under this header, in this order:

```
id,invoiceNumber,contractId,sellerCustomerId,origin,invoiceType,status,
jurisdiction,currency,issueDate,dueDate,dateOfSupply,subtotalMinor,
taxTotalMinor,grandTotalMinor,creditAppliedMinor,collectibleMinor,
creditSettledMinor,corrects,reverseCharge,paidVia,voidedAt,writtenOffAt,
outstandingMinor
```

(One line in the file; wrapped here to fit.)

Money columns are integer **minor units** and their names say so
(`grandTotalMinor` — `4999` is €49.99); do not divide by 100 in the
spreadsheet without also keeping the raw column. Timestamps are RFC 3339 UTC;
`corrects` names the invoice a credit note corrects, empty otherwise.

`outstandingMinor` is the receivable — the column to age in an AR report,
rather than `collectibleMinor`, which is frozen at issue. An **empty cell**
means the adjustment ledger was unavailable for that row: the balance is
unknown, and it is never written as `0`. The rest of the row is unaffected,
so a ledger outage costs you that one column and not the reconciliation.

**New columns are appended, never inserted.** Reconciliation files are loaded
by pipelines that address columns positionally, so reordering an existing
export would silently shift every one of them. Read by name if you can; if you
read by position, a later Fynex release may make the row longer but will not
move a column you already read.

**NDJSON** carries one list-API invoice object per line — exactly the shape
`GET /invoices` serves, so a pipeline that parses the list parses the export
with no new code.

Rows come newest first, the same order as the list. A window holding more
than 100,000 documents answers `400` with instructions to narrow the range —
refused rather than silently truncated, because a reconciliation file that
looks complete and is not is how a document goes missing from someone's
books.

**Failures:** `400` — a missing or inverted date range, an unknown filter
value, or a window over the row cap · `401` · `403`.

---

## 19. `GET /invoices/{invoiceId}/settlement`

The join between billing and money movement: which payment attempts hit this
invoice's collection link, and which payouts carried them out. Billing and
split payments live on one platform — this is the endpoint that finally
connects them.

**Returns**, newest payment first:

```json
{
  "invoiceId": 4180,
  "invoiceNumber": "UK2607AA-2608AAB",
  "paidVia": "payment_link",
  "paymentLinkId": 512,
  "payments": [{
    "paymentId": 991,
    "status": "settled",
    "amountMinor": 12000,
    "currency": "EUR",
    "createdAt": "2026-08-17T09:26:00Z",
    "payouts": [{
      "payoutId": 55,
      "status": "completed",
      "state": "finalized",
      "attributedMinor": 12000,
      "currency": "EUR",
      "completedAt": "2026-08-20T06:00:00Z"
    }]
  }]
}
```

Failed payment attempts are reported with their status — "the customer tried
twice and the second one settled" is part of the story. A payment with an
empty `payouts` array has settled but not yet been scheduled into a payout. A
payment can be split across payouts; `attributedMinor` is each payout's slice,
and the attributions sum to what left. `state` is the attribution's own
lifecycle: `reserved` (selected for a payout), `finalized` (paid out) or
`released` (returned to the pool).

Three invoices legitimately have an empty trail, and the response carries a
`note` saying which case it is rather than an ambiguous empty list: an invoice
that was **never sent** (no collection link exists), one settled by a
**matched bank deposit** (the money arrived outside the payment-link rail),
and one **discharged entirely by stored credit** (no cash moved at all).

Payout and payment detail beyond the ids lives on the Payments API — this
endpoint gives you the ids to look them up with.

**Failures:** `400` — a malformed id · `401` · `403` · `404` — unknown id, or
an invoice belonging to another seller.

---

## 20. `POST /customers`

Resolves one of your customers by e-mail, creating the record when the address
is new. The returned `id` is the `sellerCustomerId` every contract, credit
top-up and invoice refers to.

**There is no `Idempotency-Key` here, and that is the rule rather than an
omission: the e-mail address is the key.** Find-or-create on (your seller
account, e-mail) is enforced in the database, so calling this twice with the
same address returns the same customer and creates nothing the second time —
which is exactly the guarantee a client key would otherwise have to supply.

Because of that the answer is always `200`, never `201`. The directory
resolves the address without reporting whether *this* call minted the record,
and a `201` would be a guess. Read the response as "this is your customer",
not as "this customer is new".

```bash
curl -s -X POST "$FYNEX_API_BASE/customers" \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "customerRef": "crm-8842",
    "name": "Ada Lovelace",
    "companyName": "Analytical Engines Ltd",
    "currency": "EUR",
    "customerType": "company"
  }'
```

```json
{
  "id": 7,
  "email": "ada@example.com",
  "customerRef": "crm-8842",
  "name": "Ada Lovelace",
  "companyName": "Analytical Engines Ltd",
  "currency": "EUR",
  "customerType": "company",
  "createdAt": "2026-09-01T10:15:00Z"
}
```

| Field | Notes |
| --- | --- |
| `email` | Required, and the key this call resolves on. A plain address — `Ada <ada@example.com>` is `400`. |
| `customerRef` | Your own identifier, at most 128 characters. A ref already held by a **different** customer of yours answers `422`. |
| `name`, `phone`, `companyName`, `companyCountry` | Optional contact details, at most 64 / 32 / 255 / 56 characters. |
| `currency` | The customer's default billing currency (ISO 4217). A contract's own currency still wins. |
| `customerType` | `individual` or `company`; omit when you do not know. |

Details are applied **fill-if-empty**: a value another surface already
recorded — checkout, or an earlier call — is never overwritten, and an omitted
field changes nothing. To correct a stored detail, use the dashboard.

**Failures:** `400` (missing or malformed `email`, an over-length field, an
unsupported `currency`, an unknown `customerType`) · `422` (`customerRef`
already belongs to a different customer) · `429` · `401` / `403`.

## 21. `GET /contracts/{contractId}/invoices/upcoming`

What the contract's next document would carry, projected through the **same
engines that bill it**: the subscription terms that fall due, the unbilled
mid-term amendments the engine would bind to them, each open metered period
rated by the engine `POST /prices/evaluate` answers with, a per-seat period
rated from the contract's seat schedule, and the stored credit that would be
drawn down.

Until this existed the answer had to be assembled in the client from four
reads and its own arithmetic — the one implementation that is not
authoritative, which is the mistake `POST /prices/evaluate` was introduced to
end for a single price. This is the same argument for a whole document.

**Nothing is written.** No amendment pool is emptied, no credit lot is minted,
no claim is taken: it is the read-only twin of the issuance pass.

| Parameter | In | Default | Notes |
| --- | --- | --- | --- |
| `contractId` | path | — | The contract to project. |
| `at` | query | now | Project as of this instant — a date (`YYYY-MM-DD`) or an RFC 3339 timestamp. A malformed value is a `400`, never a silently substituted "now". |

```bash
curl -s "$FYNEX_API_BASE/contracts/42/invoices/upcoming" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

```json
{
  "contractId": 42,
  "asOf": "2026-09-20T12:00:00Z",
  "nextIssueDate": "2026-10-01",
  "currency": "EUR",
  "lines": [
    {
      "source": "subscription",
      "description": "Subscription — 2026-09-01 to 2026-10-01",
      "quantity": "1",
      "unitPriceMinor": 10000,
      "amountMinor": 10000,
      "periodStart": "2026-09-01",
      "periodEnd": "2026-10-01"
    },
    {
      "source": "usage",
      "description": "api.requests usage — 2026-09-01 to 2026-10-01",
      "quantity": "12000",
      "amountMinor": 4800,
      "periodStart": "2026-09-01",
      "periodEnd": "2026-10-01",
      "note": "the period is still open, so the quantity keeps accruing until it closes"
    }
  ],
  "subtotalMinor": 14800,
  "grandTotalMinor": 14800,
  "creditAvailableMinor": 5000,
  "creditAppliedEstimateMinor": 5000,
  "collectibleEstimateMinor": 9800,
  "notes": [
    "every amount is pre-tax: the recurring lane copies its tax treatment from a prior invoice on this contract at issue time, and this projection does not resolve it",
    "metered lines are rated with a zero rollover carry, as the finance summary is; the close pass resolves the real carry chain when the period closes"
  ],
  "estimate": true
}
```

| Field | Notes |
| --- | --- |
| `asOf` | The instant projected. Metered usage accrues after it. |
| `nextIssueDate` | The earliest period end that falls due — the day the next document would appear. Absent when nothing is due. |
| `currency` | The one currency the totals are in. A line in another currency is listed and **excluded** from the totals with a note; money is never converted to produce a nicer figure. |
| `source` | `subscription`, `proration`, `usage` or `seat` — which engine produced the line. |
| `quantity` | Decimal string: `1` for a recurring term, the period's aggregated quantity for usage, the period-weighted seat count for seats. |
| `unitPriceMinor` | Present only when the line **has** a single unit price. Absent for tiered, graduated, volume, package and percentage usage lines: their price varies by band or is not per unit at all, and an average here would let you recompute a different amount. |
| `amountMinor` | Pre-tax and **signed**. A mid-term downgrade credit is negative because that is what it does to the document's face value; on the issued invoice it rides as a discount on the recurring line. |
| `periodStart`, `periodEnd` | The span the line covers. |
| `note` | Why this particular line is an estimate, or why it is zero — a term still in trial, a period still accruing, a credit that lands on another line. |
| `subtotalMinor` | Sum of the included lines, pre-tax. |
| `grandTotalMinor` | The projected document total. It **equals** `subtotalMinor`: tax is not projected (see below). |
| `creditAvailableMinor` | The contract's drawable stored value in this currency. Zero while the credits capability is off. |
| `creditAppliedEstimateMinor` | What the drawdown would consume: the available balance bounded by the document total. |
| `collectibleEstimateMinor` | What a payment rail would be asked for after credit — the figure your buyer would see. |
| `notes` | Every reason the figures are estimates and every exclusion made: the absent tax, an unpriced metric, a foreign-currency line, a capability switched off. Read them; they are not decoration. |
| `estimate` | Always `true`. |

**Every figure is an estimate, and the response says so.** Metered usage keeps
accruing after `asOf`; the period close resolves a rollover carry this
projection assumes is zero; an unbilled amendment can still move before the
recurring pass binds it. Reconcile against the issued document, never the
other way round.

**Amounts are pre-tax, deliberately.** The recurring lane does not compute tax
either — it **copies** the treatment (category, rate, taxable flag) from a
prior invoice on the same contract when it issues, and resolving that needs
the document history this read does not touch. Guessing a rate would put a
number on your screen no jurisdiction agreed to, so no tax is projected and
`grandTotalMinor` equals `subtotalMinor`. Read an issued document's tax from
`GET /invoices/{invoiceId}`.

**Failures:** `400` (a malformed `contractId` or `at`) · `404` (no such
contract, or not yours — the two are deliberately the same answer) · `429` ·
`401` / `403` · `501` when the projection is not enabled on the deployment.

## 22. `GET /contracts/{contractId}/test-clock` and `POST /contracts/{contractId}/test-clock/advance`

**Test-mode (demo) accounts only.** A live account answers `403` on both: a
live subscription's renewal is real revenue and a real document sent to a real
customer, and no key may simulate that.

Subscription flows run on billing **dates**. A sandbox that makes you wait 31
real days for the first renewal is not a sandbox, so a contract can be given a
clock of its own and moved forward.

### `GET …/test-clock`

```bash
curl -s "$FYNEX_API_BASE/contracts/42/test-clock" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

```json
{
  "contractId": 42,
  "now": "2026-02-01T00:00:00Z",
  "simulated": true,
  "frozenAt": "2026-01-01T09:15:00Z",
  "updatedAt": "2026-01-01T09:16:12Z"
}
```

| Field | Notes |
| --- | --- |
| `contractId` | The contract this clock belongs to. Clocks are **per contract**: advancing one never moves another, yours or anyone else's. |
| `now` | What the billing engines treat as *now* for this contract. |
| `simulated` | `false` while the contract still runs on real time — a contract that has never been advanced has no clock row, and reading does not create one. |
| `frozenAt` | Real time when the clock was created; absent while `simulated` is `false`. With `now` it says how far the contract has been pushed. |
| `updatedAt` | When the clock last moved; absent while `simulated` is `false`. |

### `POST …/test-clock/advance`

```bash
curl -s -X POST "$FYNEX_API_BASE/contracts/42/test-clock/advance" \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "2026-02-01T00:00:00Z"}'
```

```json
{
  "clock": {
    "contractId": 42,
    "now": "2026-02-01T00:00:00Z",
    "simulated": true,
    "frozenAt": "2026-01-01T09:15:00Z",
    "updatedAt": "2026-01-01T09:16:12Z"
  },
  "advanced": true,
  "lifecycle": {
    "trialsActivated": 0,
    "trialsCanceled": 0,
    "trialsPastDue": 0,
    "renewed": 1,
    "resumed": 0,
    "canceled": 0,
    "expired": 0,
    "skipped": 0,
    "cronDisabled": false
  },
  "invoices": {
    "issued": 1,
    "sent": 1,
    "skipped": 0,
    "failed": 0,
    "passDisabled": false
  },
  "notAdvanced": [
    "usage period close (billing.usage.close_pass)",
    "usage invoicing (billing.usage.invoice_pass)",
    "dunning e-mail for a past-due subscription",
    "off-session auto-charge of an issued invoice (billing.invoice.auto_charge)"
  ]
}
```

`to` is an RFC 3339 instant. It must be **after** the contract's current clock
— read it from `GET …/test-clock` — and at most **366 days** after it.

**Re-sending the instant the clock already sits at is a no-op**: `200` with
`advanced: false`, nothing renewed and nothing issued twice. That makes the
call safe to retry. A target in the past, or more than 366 days ahead, is
`400`: a clock never runs backwards, because the documents it causes are
immutable and numbered.

The advance then runs, **for that one contract only**, the two engines the
scheduled passes use:

| Response block | What ran |
| --- | --- |
| `lifecycle` | The subscription state machine: trials ending, pauses elapsing, scheduled cancellations and fixed ends taking effect, and terms rolling over. Each renewal emits a `subscription_renewed` event on the contract's revenue timeline, exactly as the cron's would. Counts are subscriptions, not amounts. |
| `invoices` | The recurring invoice lane: the renewed term's document, composed from the contract's previous invoice, numbered, and sent. At most one per advance. `skipped` covers a term already claimed by an earlier advance or by the real cron, a contract with no prior invoice to continue from, no customer on the contract, or a currency disagreement. |

`lifecycle.cronDisabled` and `invoices.passDisabled` name an operator switch
that stopped half the loop — `billing.subscription.lifecycle_cron` and
`billing.recurring.invoice_pass` respectively. If either is `true`, ask Fynex
to enable the flag rather than debugging your integration; see
[Sandbox & testing](/billing-api/v1/docs/sandbox).

**`notAdvanced` is the honest part.** This clock moves the subscription state
machine and the recurring invoice. It does **not** close usage periods, mint
usage invoices, send dunning e-mail, or run off-session auto-charge — those
stay on real time in their own passes. Do not build a test that waits on one
of them after an advance.

**Failures:** `400` (a malformed `contractId`, a missing or unparseable `to`, a
target at or before the current clock, or one more than 366 days ahead) ·
`403` (a live-mode account, or an account whose mode cannot be confirmed) ·
`404` (no such contract, or not yours — deliberately the same answer) · `429` ·
`401` · `500`.

---

## Dashboard-only routes not on this surface

The platform's **cost model** (fynex-billing#277: `CostRateCard`, the cost
engine and its dry run) is served on the dashboard surface `/billing/v1`
only — `POST|GET /billing/v1/cost-rate-cards`, `GET …/{id}`,
`POST …/{id}/activate`, `POST /billing/v1/costs/evaluate` — behind the
backoffice `billing:read` / `billing:update` permissions. Nothing of it is
published here yet; the object's shape is still moving, and a public route is
a one-way door. Reference: `docs/billing-cost-model.md`.

## Status codes, at a glance

| Code | When |
| --- | --- |
| `200` | Success. Also a replayed write: the same `Idempotency-Key` again, or a customer that already existed. |
| `201` | Created — the first call of a write that minted something (`POST /contracts`, `POST /contracts/{contractId}/amendments`, `POST /invoices`, `POST /contracts/{contractId}/subscriptions`, `POST /contracts/{contractId}/credits/top-up`). |
| `400` | Malformed id, paging value, date, or an unrecognized `origin`/`status`/`invoiceType`. |
| `401` | Missing or invalid key. Body may be plain text. |
| `403` | Valid key, seller account not active. |
| `404` | Unknown id — or one belonging to another seller. |
| `422` | The object exists but the action does not apply — `POST /send`, the subscription writes, an `Idempotency-Key` already spent on a different credit grant, contract or invoice, a `customerRef` already held by another customer, an amendment whose `expectedBaseVersion` is stale or whose status transition is illegal. |
| `429` | Rate limited. Honour `Retry-After`. `POST /contracts`, `POST /contracts/{contractId}/amendments` and `POST /invoices` each carry an extra per-seller quota on top of the surface-wide budget. |
| `500` | Server fault. Retry GETs with backoff. |
| `503` | The per-seller write quota's limiter is unreachable, so those three writes fail closed. Honour `Retry-After` and retry — see [Errors → rate limiting](/billing-api/v1/docs/errors#when-the-write-quotas-fail-closed). |
| `413` | The request body exceeds 1 MiB. |
| `501` | Capability not enabled for this deployment (credits). |

Every error body is `{"error": "…"}` except the auth layer's, which may be
plain text — treat any non-2xx as failed regardless of body shape.

---

# Workflows

End-to-end recipes for the things integrators actually build. Each one names
the endpoints, the order, and the failure modes worth handling.

## Collect payment on an invoice

Invoices are issued by the billing engine (subscription renewals, usage
period close) or by your team in the dashboard. This API turns an issued
invoice into something a customer can pay.

```bash
curl -s -X POST $FYNEX_API_BASE/invoices/4180/send \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

```json
{
  "invoice": { "id": 4180, "status": "sent", "paymentLinkId": 991, "...": "..." },
  "paymentLinkUrl": "https://pay.example-host/p/7bc1f2a9e4d5"
}
```

The URL points at the Fynex hosted payment page for your deployment (the host is configured per environment, so do not hard-code it — always use the URL this response returns). Send it to your customer, embed it, or redirect to it. When the document is
configured for email delivery, Fynex also emails the customer — calling this
endpoint is what triggers that.

**Retrying is safe, and needs no idempotency header.** The invoice's unique
payment-link association is the durable safeguard: an invoice that already has
a link returns that same link rather than minting a second, even for
simultaneous calls, and does not re-send the email.

**The payment carries the document.** Whichever rail collects an invoice — the
hosted link or off-session auto-charge — the resulting payment is stamped with
what it settled, so you never have to reconstruct it from an order reference:

- The payment link's `metadata` holds `billingInvoiceId`, `invoiceNumber`,
  `contractId`, `agreementNumber` and `sellerCustomerId`. The contract and its
  agreement number reach the payments side nowhere else.
- The payment row carries `billing_invoice_id`, and so does its checkout
  session — a direct answer to "which invoice did this payment collect", with
  no join through the link.
- The acquirer's order description reads `Invoice <number>` (Paysafe
  `description`, Solidgate `order_description`), which is what makes the
  document visible in acquirer dashboards and dispute correspondence. The
  merchant reference is deliberately unchanged: it is the duplicate-detection
  and settlement-mapping key and stays machine-shaped.
- `PaymentCompleted` carries `invoiceNumber` and `contractId` when the payment
  collected an invoice, so it can be joined to `InvoicePaid` and to the
  document itself.

Three cases answer `422`, and they are not retryable — the state has to
change first:

| Message | Meaning |
| --- | --- |
| `invoice is collected by bank transfer and cannot create a payment link` | The document instructs the buyer to wire money to a named account. A simultaneously payable card link would let a transfer and a card charge both succeed. |
| `invoice has nothing left to collect` | Zero total, or stored credit already covers it. There is nothing to ask the customer for. |
| `invoice is not in a sendable state` | Not issued yet (`draft`), or already `paid`, `voided` or `written_off`. A settled invoice never hands out a payment link. It is also the catch-all: if `status` reads `issued` and send still answers this, the document itself is faulty (a collection snapshot that is missing or unreadable) — nothing you send will fix it, so raise it with Fynex rather than retrying. |

## Know when an invoice is paid

`InvoicePaid` on the webhook pipe is the push signal (see **Webhooks**);
polling remains right for reconciliation.

Do not assume the settlement was something you or the buyer did. A seller can
enable off-session collection (`billing.invoice.auto_charge`), and then a sent
or overdue invoice is charged against the customer's saved card by a
background loop — `paidVia` still reads `payment_link`, because it settles on
the same rail. Sellers can likewise have documents raised for them by the
recurring and usage invoice passes. Both are per-seller operator switches, off
until turned on, and both mean `GET /invoices` can change with no call of
yours: reconcile against the list for a period rather than against the
documents you happen to have touched.

```bash
curl -s $FYNEX_API_BASE/invoices/4180 \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

Read `invoice.status`:

| Status | Meaning |
| --- | --- |
| `draft` | Not yet issued. Not a legal document; not collectible. |
| `issued` | Numbered and legally real; no collection instrument yet. |
| `sent` | A payment link exists; awaiting payment. |
| `paid` | Settled. `paidVia` says how: `payment_link` (hosted checkout), `bank_transfer` (a matched deposit) or `credit` (stored credit covered it in full). |
| `overdue` | Past its `dueDate` and still unpaid. |
| `voided` | Cancelled before money moved; `voidedAt` and `voidReason` explain. |
| `written_off` | Collection abandoned; `writtenOffAt` and `writeOffReason` explain. |

Treat this list as open: a status you do not recognize should not crash your
integration. Branch on the ones you handle and fall through for the rest.

Poll open invoices every few minutes at most; a fixed 15-minute sweep over
`GET /invoices` is usually better than polling each document. Bank transfers
settle when the deposit is matched, which is hours-to-days — do not build a
tight loop waiting for one.

A credit note (`invoiceType: "credit_note"`) is a **separate document** that
corrects an earlier one, named in `originalInvoiceNumber`. It does not change
the original: to compute what a customer owes, sum the invoice and its credit
notes rather than expecting the original to shrink. Fetch them with
`?corrects=<invoiceNumber>`.

## Reconcile an invoice against its payout

"The customer paid — where is the money?" is one call per invoice:

```bash
curl -s "$FYNEX_API_BASE/invoices/4180/settlement" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

Read it in this order: each entry in `payments` is one attempt on the
invoice's collection link, failed ones included — the newest `settled` one is
your money. Inside it, each entry in `payouts` is a payout's claim on that
payment: `state: "finalized"` with a `completedAt` means it left; `reserved`
means it is scheduled; an empty `payouts` array means the payment settled but
has not been picked into a payout yet. `attributedMinor` is that payout's
slice — a payment can be split across payouts, and the slices sum to what
left.

An invoice settled by bank transfer or stored credit has no link trail, and
the response's `note` says which case you are looking at — do not treat an
empty `payments` list as an error. Payout detail beyond the id lives on the
Payments API; this call gives you the id to look it up with.

## Reconcile a period

**For month-end, take the file.** One call returns every invoice of the
window as CSV (or NDJSON — the list API's objects, one per line), with money
in integer minor units and column names that say so. Both dates are required;
there is deliberately no default window:

```bash
curl -s "$FYNEX_API_BASE/invoices/export?issuedFrom=2026-08-01&issuedTo=2026-09-01" \
  -H "Authorization: Bearer $FYNEX_API_KEY" -o invoices_2026-08.csv
```

The paged list below remains right when you are feeding an application rather
than closing books. Bound it by issue date rather than walking history until
you cross the boundary — the range is half-open (`issuedFrom` inclusive,
`issuedTo` exclusive), so adjacent months never double-count a document:

```bash
# First page of August
curl -s "$FYNEX_API_BASE/invoices?issuedFrom=2026-08-01&issuedTo=2026-09-01&limit=100" \
  -H "Authorization: Bearer $FYNEX_API_KEY"

# Next page: pass the previous response's nextCursor
curl -s "$FYNEX_API_BASE/invoices?issuedFrom=2026-08-01&issuedTo=2026-09-01&limit=100&cursor=4081" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

Filters worth combining:

- `contractId=42` — one customer relationship.
- `sellerCustomerId=7` — every document addressed to one of your customers,
  across contracts. This is how you pull a customer statement without walking
  the whole period.
- `status=sent` — one lifecycle state (`draft`, `issued`, `sent`, `paid`,
  `overdue`, `voided`, `written_off`).
- `invoiceType=credit_note` — corrections only. The full set is `standard`,
  `credit_note`, `simplified` (retail below the threshold) and `modified` (UK
  retail above it, VAT-inclusive line prices).
- `corrects=UK2607AA-2608AAB` — the credit notes issued against one invoice
  number, without scanning history for them.
- `origin=usage` — the subsystem that produced the document: `recurring`,
  `usage`, `milestone`, `project`, `one_time`, `adhoc`, `marketplace`.
  (`subscription` is a deprecated alias of `recurring`: still accepted, no
  longer produced, and it resolves to the same set as `recurring` — see below.)

`origin`, `status` and `invoiceType` reject an unrecognized value with `400`,
so a typo cannot masquerade as "no such invoices". `contractId` and `corrects`
are matched as given: a well-formed but wrong value legitimately returns an
empty page, so check those two against `GET /contracts` and the invoice number
you meant.

`origin=recurring` and `origin=subscription` return the same rows. The second
is the pre-schema name, and documents issued before the rename still carry it
— filtering either way includes both, so a monthly report cannot silently lose
the older half.

`customerName` and `customerEmail` are returned on the single-invoice read and
on send, but **not** on list rows: they live in the document's frozen payload,
and reading them for a whole page would mean parsing every document. To group
a report by customer, filter with `sellerCustomerId` rather than fetching each
invoice — that keeps a monthly reconciliation to a handful of requests instead
of one per document.

For accounting, the figures per document are `grandTotalMinor` (what was
invoiced), `creditAppliedMinor` (funded by stored credit rather than cash),
and `collectibleMinor` (the grand total less that credit — what collection
asks the customer for).

Two traps worth stating plainly:

- **`creditSettledMinor` is not a payment total.** It counts only the stored
  credit drawn down; a card- or transfer-paid invoice reports `0` there.
- **`collectibleMinor` does not drop to zero when an invoice is paid.** It
  describes the ask, not the outcome.

So "has this been paid?" is answered by `status` (and `paidVia` for how), never
by arithmetic on the amounts.

Because paging is keyset, not offset, documents issued while you are walking
the pages never shift rows into or out of a page you already fetched. Start a
fresh walk to pick them up.

## Watch usage against plan limits

For metered contracts, the snapshot answers "where is this customer in the
current period":

```bash
curl -s $FYNEX_API_BASE/contracts/42/usage \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

```json
{
  "contractId": 42,
  "metrics": [
    {
      "metricName": "api_calls",
      "used": "10250",
      "includedUnits": "10000",
      "capQuantity": "50000",
      "capMode": "hard",
      "percentOfCap": "20.5",
      "percentOfPlan": "102.5",
      "periodStart": "2026-08-01",
      "periodEnd": "2026-08-31"
    }
  ]
}
```

Useful signals:

- `percentOfPlan` above 100 means the customer is into overage — that is what
  will be rated onto the next usage invoice.
- `capQuantity` with `capMode: "hard"` is the ceiling enforcement uses. Warn
  customers well before `percentOfCap` reaches 100 rather than at it.
- Quantities are decimal strings; compare with a decimal type.

An unknown `contractId` answers `404`. A real contract with no metered usage
answers `200` with an empty `metrics` array — that is a valid state, not an
error.

Usage aggregates continuously and closes at period end, so a snapshot is a
live read, not a final invoice figure. Reconcile money against invoices.

## Reconcile stored credit

Balances across all contracts:

```bash
curl -s $FYNEX_API_BASE/credits \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

```json
{
  "balances": [
    {"currency": "EUR", "creditType": "purchased", "balanceMinor": 250000, "isLiability": true}
  ]
}
```

`isLiability: true` marks credit that was **paid for** — `purchased`,
`enterprise` and the engine-minted `proration` (unserved time returned on a
mid-term downgrade) — which is unearned revenue you still owe service against.
Everything you granted (`promotional`, `manual`, `gift`, `ai_token`,
`marketplace`) is not a liability. Finance wants these separated, so do not
sum them blindly. Paid-for credit also never expires; granted credit may.

One contract's balances plus its ledger:

```bash
curl -s "$FYNEX_API_BASE/contracts/42/credits?limit=50" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

The ledger is append-only and newest-first. `kind` is `topup` (credit granted
or bought), `deduction` (consumed into an invoice) or `expiry` (a lapsed lot
removed); `signedDeltaMinor` is positive for topups and negative for the other
two, and `invoiceId` links a deduction to the invoice it funded. Corrections are new rows, never edits, so
replaying the ledger from the beginning always reproduces the current
balance.

Page it the same way as invoices: `limit` sets the page, and while `hasMore`
is true you pass `nextCursor` back as `cursor`. A long-lived contract's
history exceeds one page, and a ledger you cannot read to the end cannot be
reconciled.

## See what the next invoice will carry

`GET /contracts/{contractId}/invoices/upcoming` projects the contract's next
document — before it exists, and without writing anything.

```bash
curl -s "$FYNEX_API_BASE/contracts/42/invoices/upcoming" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

The `lines` array is the document as it would be composed, each line tagged
with the engine that produced it: `subscription` (a term falling due, priced
at a scheduled plan change when one takes effect by the term's end),
`proration` (an unbilled mid-term amendment the engine would bind to that
term — a charge as an extra line, a credit as a discount on the recurring
one), `usage` (an open metered period rated by the same engine
`POST /prices/evaluate` answers with) and `seat` (a per-seat period rated from
the contract's seat schedule, to date). `nextIssueDate` is the day the
document would appear, and `collectibleEstimateMinor` is what your buyer would
be asked for after stored credit is drawn down.

**Every figure is an estimate, and `estimate: true` says so on every
response.** Metered usage keeps accruing after `asOf`; the period close
resolves a rollover carry this projection assumes is zero; an amendment can
still move before the recurring pass binds it. Amounts are also **pre-tax**:
the engine copies a document's tax treatment from a prior invoice on the same
contract when it issues, so no tax is projected here and `grandTotalMinor`
equals `subtotalMinor`. Read the `notes` array — it names every reason the
figures are estimates and every exclusion made (an unpriced metric, a
foreign-currency line, a capability switched off), which is what stops a
number in this response from being read as a commitment.

Use it to show a customer what is coming, to check a plan change landed
before the term bills, or to catch an unpriced metric while there is still
time to price it. Reconcile against the **issued** document
(`GET /invoices/{invoiceId}`), never the other way round.

## Track subscription state

```bash
curl -s "$FYNEX_API_BASE/subscriptions?contractId=42" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

To answer "is this customer currently being billed, and for how much", read
`status`, `priceMinor` + `currency`, and `billingFrequency`. There is no
separate plan object — those three fields *are* the plan.

Watch for:

- `pendingPriceMinor` / `pendingPriceChangeAt` — a scheduled change (usually a
  downgrade) that takes effect at term end. Showing only `priceMinor` will
  misinform a customer who already requested a change.
- `cancelRequestedAt` / `cancelEffectiveAt` — cancellation with notice. The
  subscription keeps serving until the effective date, so `status` alone is
  not "are they leaving".
- `trialEnd` with `status: "trial"` — not yet paying.
- `status: "past_due"` — collection failed. **What happens next depends on a
  switch the seller controls**, so do not hard-code either answer:
  - With off-session collection enabled (`billing.invoice.auto_charge`), a
    failed charge is retried on a bounded schedule — a few attempts, spaced
    apart — and the subscription is moved to `past_due` only once that budget
    is spent. It can come back on its own when a later payment succeeds, which
    is what `BillingSubscriptionRecovered` announces. Do not treat `past_due`
    as terminal and do not start your own retry loop against it; you would be
    charging the same card twice.
  - Without it, nothing retries: `past_due` is a queue for you to work, and
    the way out is the customer paying the outstanding invoice or a new card
    being added.

  In both cases the events to watch are `BillingSubscriptionPastDue` and
  `BillingSubscriptionRecovered`, and the invoice's `outstandingMinor` is what
  says how much is actually still owed.
- `pauseEndsAt` — an auto-resume date for a paused subscription.

Lifecycle changes (cancel, pause, plan change) are dashboard operations in
this version.

## Retries and rate limits

Reads are safe to retry. So is `POST .../send`: the invoice can hold only one
payment link, so a retry returns the existing one.

- `429` — you exceeded the per-seller budget. Wait the `Retry-After` seconds;
  do not retry sooner. `X-RateLimit-Remaining`, when present, lets you slow
  down before you hit it — the limiter fails open during an outage, and then
  no rate-limit headers are sent at all.
- `5xx` — retry with exponential backoff and jitter.
- `4xx` other than `429` — do not retry; the request has to change.

A retry loop that ignores `Retry-After` turns one throttled request into a
sustained overage. If you are paging a large history, a small delay between
pages is cheaper than being throttled mid-walk.

---

# Usage ingestion

Metered billing has two halves. This API reads the meter — `GET
/billing-api/v1/contracts/{contractId}/usage` returns where a contract stands
in its open period. **Writing to that meter happens on a different prefix**,
`/billing-api/v1/usage`, documented here.

Same API, same credential: `Authorization: Bearer sk_test_…` / `sk_live_…`,
same seller tenancy, same `{"error": "…"}` envelope.

> **A second, older path exists.** Metering shipped before this API did and
> took the top-level prefix `/usage/v1`. Every route below still answers there
> too, unchanged — but `/billing-api/v1/usage/…` is the documented one, and new
> integrations should use it. The single exception is the inbound webhook
> receiver in §5, which stays on `/usage/v1` on purpose: it is authenticated by
> payload signature rather than by your key, and every operation under
> `/billing-api/v1` is key-gated.

The loop is: **register a metric → price it → send events → read the meter →
the period closes into an invoice.**

> **One convention differs here, and it matters.** Everything under
> `/billing-api/v1` reports money in integer minor units. A *price
> configuration* is the exception: unit prices and tier amounts are decimal
> strings in **major** units (`"0.0001"` is one hundredth of a cent per unit),
> because per-unit rates are routinely finer than a minor unit. The rate is
> exact; the rounding to minor units happens once, at invoicing, by the policy
> the config names. Amounts you read back on an invoice are minor units as
> usual.

---

## 1. Register a metric

A metric is the meter's identity: what is counted, in what unit, and how
several events in one period combine.

```bash
curl -s -X POST $FYNEX_API_BASE/usage/metrics \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"api_calls","unit":"call","aggregation":"sum","description":"Billable API requests"}'
```

```json
{
  "name": "api_calls",
  "version": 1,
  "unit": "call",
  "aggregation": "sum",
  "description": "Billable API requests"
}
```

| Field | Rules |
| --- | --- |
| `name` | Registry identifier — this is what events reference. |
| `unit` | Free text, at most 32 characters (`call`, `GB`, `token`, `seat`). |
| `aggregation` | `sum`, `max`, `min`, `last`, `count` or `count_unique`. How the period's events collapse into one billable quantity. |
| `uniqueKey` | `count_unique` only: the event-metadata key whose distinct values are counted — a user id, an endpoint, a tenant. Required there, forbidden elsewhere. |
| `description` | Optional, at most 256 characters. |

Answers `201` with the registered metric, or `400` naming the field that was
wrong.

A `count_unique` metric answers "how many *different* users called", where
`count` answers "how many calls". Its events **must** carry the `uniqueKey`
field in `metadata` (`400` otherwise), and at most **1,000 distinct values**
count per contract and period: past that, new values stop counting and the
balance is flagged as overflowed — the figure becomes a floor. If your
cardinality is legitimately higher, meter with `count` and dimension in your
own analytics instead. Metrics are versioned: `version` increments when a registration
changes the definition, and events are attributed to the version current when
they arrive. `uniqueKey` is part of that definition, like `unit` and
`aggregation`: it cannot be edited in place — registering the same name again
with a different `uniqueKey` creates version N+1, and events keep being
attributed to whichever version is in force when they arrive.

There is no time-weighted aggregation — GB-hours, active-seat-days and the
like. Compute the weighted figure on your side and send it as the event
quantity of a `sum` metric; a `max` or `last` metric over a gauge reading is
the other honest shape.

- `GET /billing-api/v1/usage/metrics` — every metric you have registered.
- `GET /billing-api/v1/usage/metrics/{name}` — one metric, `404` when it is not registered.

## 2. Price the metric on a contract

Pricing is per contract and per metric, and it is versioned by date — a new
configuration does not rewrite history, it takes effect from a date you state.

```bash
curl -s -X PUT "$FYNEX_API_BASE/usage/contracts/42/metrics/api_calls/price" \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "effectiveFrom": "2026-09-01",
    "config": {
      "scheme": "graduated",
      "currency": "EUR",
      "rounding": "half_up",
      "unitPrice": "0",
      "tiers": [
        {"upTo": "10000", "unitPrice": "0.004", "flatAmount": "0"},
        {"upTo": null,    "unitPrice": "0.002", "flatAmount": "0"}
      ],
      "allotment": {"includedUnits": "1000", "rollover": "none"},
      "commitment": {"minimumMinor": 5000, "spendCapMinor": 500000}
    }
  }'
```

### The seven pricing schemes

| `scheme` | How the quantity is charged |
| --- | --- |
| `per_unit` | `units × unitPrice`. One rate, no bands. |
| `graduated` | Every band charges its own rate for the units inside it — progressive, like income tax. |
| `volume` | The band the **total** quantity lands in prices **all** units at that band's rate. |
| `tiered` | Stairstep: the band the total lands in charges its `flatAmount`, whatever the exact count. |
| `package` | Per started block: `ceil(quantity / packageSize) × unitPrice`, where `unitPrice` is the price of one package. A partial package charges in full — 1,001 units at "per 1,000" is two packages. |
| `percentage` | `percentBps` basis points (100 = 1%) of the aggregated quantity, which for this scheme is itself a monetary amount in major units — a GMV or transaction-value meter. |
| `per_seat` | `unitPrice` per seat per FULL period, prorated to the day: `unitPrice × seatDays ÷ periodDays`. Rated from a recorded seat history rather than from ingested events — see [Per-seat pricing](#per-seat-pricing) below. |

`graduated` and `volume` are the classic trap — same bands, same quantity,
different money. Read the two rows above before choosing. There is no `flat`
scheme on purpose: a fixed per-period fee is what a subscription price is,
and a usage floor is `commitment.minimumMinor` on any scheme.

### The rest of the configuration

| Field | Meaning |
| --- | --- |
| `currency` | ISO 4217. Must match the contract's currency. |
| `rounding` | Applied once, when the exact decimal amount collapses to minor units: `half_up`, `half_even`, `up` or `down`. No default — state it. |
| `unitPrice` | The `per_unit` rate, the `package` scheme's price per package, and the `per_seat` scheme's price per seat per full period. Decimal string in major units; ignored by banded schemes. |
| `packageSize` | The `package` scheme's block size in units, decimal string. Required there, forbidden elsewhere. |
| `percentBps` | The `percentage` scheme's rate in integer basis points (100 = 1%). Required there, forbidden elsewhere. |
| `tiers[].upTo` | The band's inclusive upper bound in units. `null` marks the last, unbounded band. Bands are ordered and contiguous from zero. |
| `tiers[].unitPrice` | The rate for `graduated` and `volume`. |
| `tiers[].flatAmount` | The flat charge for `tiered`. |
| `allotment.includedUnits` | The first N units of each period rate to zero. |
| `allotment.rollover` | `none`, or `rollover` to carry an unused allowance into the next period. |
| `commitment.minimumMinor` | Floor: the period bills at least this much, in minor units. |
| `commitment.spendCapMinor` | Ceiling on the money the period can bill, in minor units. |
| `commitment.usageCap` | Ceiling on the billable quantity, as a decimal string. |

Answers `200` with the stored configuration and its `version`. `GET` on the
same path returns the current one, or `404` with `this metric has no price
configured` — which is the check to run before you start sending events.

> A **usage limit policy** is a separate control from `commitment.usageCap`:
> it is what `GET /billing-api/v1/contracts/{contractId}/usage` reports as
> `capQuantity` / `capMode`, and a `hard` policy **rejects ingestion past the
> cap** (see the failure table below). A `soft` one only alerts.

### Per-seat pricing

`per_seat` prices what a customer HOLDS rather than what it consumes, so it is
the one scheme that is not rated from ingested events. It reads a **seat
history**: an append-only record of how many seats the contract holds and from
when, so a period with mid-cycle changes can be priced day by day.

Configure it against the reserved metric **`platform.seat.active`**:

```bash
curl -s -X PUT "$FYNEX_API_BASE/usage/contracts/42/metrics/platform.seat.active/price" \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "effectiveFrom": "2026-01-01",
    "config": {
      "scheme": "per_seat",
      "currency": "EUR",
      "rounding": "half_up",
      "unitPrice": "10.00"
    }
  }'
```

**The metric and the scheme are reserved for each other.** `per_seat` is
configurable **only** on `platform.seat.active`, and `platform.seat.active`
accepts **only** `per_seat` — either mismatch answers `400`. The pairing is not
housekeeping: a `per_seat` price on an ordinary metric is a period the close
pass can never rate (it has a quantity, and this scheme has no use for one), so
it would simply never bill; and any other scheme on the seat metric would rate
your seats from whatever quantity happened to be ingested against it rather
than from the recorded seat history.

`unitPrice` is the price of ONE seat for a FULL period. `allotment`,
`allotment.rollover` and `commitment.usageCap` are **refused** on this scheme —
they are denominated in "units", and the unit here is a day-weighted seat
integral rather than a consumption counter, so the same number would not mean
the same thing. `commitment.minimumMinor` and `commitment.spendCapMinor` work
exactly as they do everywhere else.

**How a period is priced.** Seats are integrated over **UTC calendar days**,
and each day is charged at the seat count that day ENDS with — the count in
effect after every seat change effective on that day or earlier:

```
amount = unitPrice × seatDays ÷ periodDays
```

Two consequences worth stating, because they are what everyone asks:

- A seat added on a day is charged for that day.
- A seat added **and** removed on the same day is charged for nothing. The day
  is not charged once per change; it is charged once, at the count the day ends
  with — so a same-day add and remove cannot double count.

**Worked example.** A contract on €10.00 per seat, January 2026 (31 days). It
opens the month with 3 seats, goes to 5 on the 11th, and back to 4 on the 21st:

| Days | Seats | Seat-days |
| --- | --- | --- |
| Jan 1–10 (10) | 3 | 30 |
| Jan 11–20 (10) | 5 | 50 |
| Jan 21–31 (11) | 4 | 44 |
| **Total** | | **124** |

124 seat-days ÷ 31 days = **4 seat-equivalents**, so the period bills
€40.00 — not €50.00 (the peak) and not €30.00 (the opening). Re-rating the
same history always produces the same amount; a correction is a new seat
change, never an edit of a recorded one.

**How a per-seat period is billed.** Exactly like every other metric's, and on
the same schedule: when the period has ended, it closes into one usage invoice
line and the invoicing lane puts that line on a document. Two things are worth
knowing because they are visible on the artifacts:

- The line's `quantity` is the period's **seat-days** — 124 in the example
  above, not 4. Seat-days is the exact integer the amount is derived from;
  the divisor (`periodDays`) and the seat-equivalent figure
  (`seatEquivalents`) are in the line's `ratingBreakdown` beside the day-run
  trace. The amount on the line is already the prorated money, so a document
  reads €40.00 whatever the quantity column says.
- A period with **no** seats recorded still closes, at zero — the same way a
  metric with no events does, so a `commitment.minimumMinor` trues up on
  silence rather than being skipped.

Because seats are not ingested, this lane is driven by the price document
rather than by arriving events: a contract is billed for seats from the first
period its per-seat price is effective for, on the contract's own billing
cycle. Periods that ended before the price existed are never billed
retroactively.

**Recording seat changes is not on this API yet.** Seats are recorded and read
on the dashboard surface — `POST` and `GET /billing/v1/contracts/{contractId}/seats`
— which needs a dashboard session, not a seller key. A seller-key route for
seat changes is a later slice; publishing one is a one-way door and the wire
shape of a seat event is exactly what would move. Until then, a `per_seat`
price you configure here is priced from the history recorded there, and
`GET /billing/v1/contracts/{contractId}/seats?periodStart=…&periodEnd=…`
returns the day-by-day breakdown above.

### Try a price before you commit to it

`POST /billing-api/v1/prices/evaluate` runs a configuration through the same
engine that bills, at any quantities you name — pure, nothing stored, no
contract required. It is how to see what `graduated` and `volume` do to the
same bands before agreeing a term, and it is what the number shown to a
customer during negotiation should come from.

```bash
curl -s -X POST "$FYNEX_API_BASE/prices/evaluate" \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config": { …the same config… }, "quantities": ["0", "5000", "12000"]}'
```

Each result carries `amountMinor` (what the period would bill, after the caps
and the minimum), the flags saying which of those limits acted, and the exact
per-band `lines`. Up to 100 quantities per call, so a whole price curve is one
request.

A `per_seat` configuration answers `422` here: that scheme is rated from the
contract's seat schedule and is not evaluable per quantity — there is no
quantity that expresses *when* the seats changed. Read the period's amount and
its day-by-day breakdown from
`GET /billing/v1/contracts/{contractId}/seats?periodStart=…&periodEnd=…`
instead.

## 3. Send events

```bash
curl -s -X POST $FYNEX_API_BASE/usage/events \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contractId": "42",
    "metric": "api_calls",
    "quantity": "1250",
    "occurredAt": "2026-09-14T10:22:31Z",
    "idempotencyKey": "req-2026-09-14-8f21",
    "metadata": {"region": "eu-west-1"}
  }'
```

```json
{ "status": "ingested", "eventId": 91422, "metered": true }
```

| Field | Rules |
| --- | --- |
| `contractId` | The contract the usage belongs to, as a string. |
| `metric` | A registered metric name. |
| `quantity` | Decimal **string** — a JSON number is a float, and metered quantities must not pass through one. |
| `occurredAt` | RFC 3339. When the usage happened, not when you sent it: this is what places the event in a billing period. |
| `idempotencyKey` | Your own key for this event. Resending the same key with the same payload is a no-op. |
| `metadata` | Optional JSON object, carried for your own audit. |

`201` when the event was recorded, `200` with `"status": "duplicate"` when the
idempotency key was already seen. Retrying is always safe.

Two policies worth knowing before you design your keys:

- **The dedup window is unbounded.** Keys are unique per seller for the
  lifetime of the data — not a rolling window — so a key seen once is a
  duplicate forever. Derive keys from the event's identity (source record id,
  timestamp), never from a counter you might reset.
- **Backdating has no lower bound; the future is refused.** `occurredAt` may
  be arbitrarily far in the past — there is no backdating window to configure
  or to fall outside of. The only temporal rejection is an `occurredAt` ahead
  of now. Two edges worth knowing: an event older than the contract's first
  billing period is stored but stays unassigned until aggregation picks it
  up, and an event landing in a **closed** period follows the next rule down.
- **A late event never rewrites a closed period.** Ingestion compares
  `occurredAt` against the metric's close watermark: an event older than the
  last closed period is accepted and flagged for the correction workflow
  instead of silently changing an amount that may already be on an issued
  invoice. Corrections are operator-reviewed, so systematically late feeds
  should be fixed at the source rather than relied on.

### `metered: false` is the failure that looks like success

An accepted event is stored, but it only reaches the meter if the contract has
an active subscription whose schedule covers `occurredAt`. When it does not,
the response is still `201`, `metered` is `false`, and `message` says so:

```json
{
  "status": "ingested",
  "eventId": 91423,
  "metered": false,
  "message": "event stored but not attributed to a billing period; it will not appear on the usage meter until an active subscription's schedule covers occurredAt"
}
```

**Check this flag.** Ignoring it is how a month of usage goes unbilled with
every call answering 2xx.

### Batches

```bash
curl -s -X POST "$FYNEX_API_BASE/usage/events:batch" \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":[ {...}, {...} ]}'
```

```json
{
  "ingested": 2,
  "duplicates": 1,
  "rejected": 1,
  "items": [
    {"index": 0, "status": "ingested",  "eventId": 91424, "metered": true},
    {"index": 1, "status": "duplicate", "eventId": 91380, "metered": true},
    {"index": 2, "status": "rejected",  "reason": "unknown metric \"api_call\""},
    {"index": 3, "status": "ingested",  "eventId": 91425, "metered": true}
  ]
}
```

Answers `200` and reports each event by its `index`; a rejected item does not
stop the others. Two whole-batch failures exist: `413` when the batch holds
more than **500 events** (split it — nothing in a refused batch is recorded),
and `500` on an infrastructure fault — retry the entire batch, the idempotency
keys make that safe.

### CSV

`POST /billing-api/v1/usage/csv` takes `multipart/form-data` with two parts: `file` (the
CSV) and `mapping` (one JSON object describing which column is which). It is
the path for backfills and ERP exports rather than live traffic.

## 4. Read the meter back

Ingested and metered usage appears on this API:

```bash
curl -s "$FYNEX_API_BASE/contracts/42/usage" \
  -H "Authorization: Bearer $FYNEX_API_KEY"
```

The snapshot is a live read of the open period — it is not a closed figure.
When the period closes, the rated usage becomes invoice lines, and those are
what you reconcile money against.

## 5. Receiving usage from a third party

If the system that produces the usage is not yours to change — an ERP, a
vendor's platform — register an inbound endpoint and give them its URL instead
of your API key:

```bash
curl -s -X POST $FYNEX_API_BASE/usage/webhook-endpoints \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Acme ERP nightly meter"}'
```

The response carries the endpoint and **the signing secret, once** — it is not
retrievable later. The sender then posts usage to
`POST /usage/v1/webhooks/{token}`, signing the body with that secret. Manage
them with `GET /billing-api/v1/usage/webhook-endpoints`, `POST
/billing-api/v1/usage/webhook-endpoints/{id}/rotate-secret` and `POST
/billing-api/v1/usage/webhook-endpoints/{id}/revoke`.

**These are inbound.** They are how usage gets *in*; they are not
notifications about your billing. There are no outbound Billing webhooks in
v1 — for invoice settlement, poll.

## 6. When an event cannot be processed

Events that arrive over asynchronous paths — inbound webhooks, CSV rows —
cannot answer the sender, so a failure is parked instead of lost:

- `GET /billing-api/v1/usage/dead-letters` — what is parked, with the reason and the
  attempt count.
- `POST /billing-api/v1/usage/dead-letters/{id}/redrive` — reprocess one after fixing the
  cause (registering the missing metric, for instance).
- `POST /billing-api/v1/usage/dead-letters/{id}/discard` — abandon one deliberately.

Synchronous calls (`/events`, `/events:batch`) never dead-letter: the caller is
present, so the rejection comes back as an HTTP error.

## Failure contract

| Status | When |
| --- | --- |
| `400` | The event is malformed, `occurredAt` is in the future, or a **hard** usage cap is already exceeded — the event is not recorded. |
| `401` | Missing or invalid key. This surface answers only "not authorized", never the account's state. |
| `404` | Unknown metric, or a contract that is not yours. |
| `409` | The `idempotencyKey` was used before with a **different** payload. Same key, same payload is a duplicate (`200`), not a conflict. |
| `413` | The batch holds more than 500 events. Nothing in it is recorded — split it and resend. |
| `500` | Infrastructure fault. Retry — idempotency keys make that safe. |

Error bodies are the same `{"error": "…"}` envelope as the rest of billing.

---

# Webhooks

Billing emits signed webhook events through the same delivery pipe as the
Payments API: one endpoint registration, one signature scheme, one retry
policy — a receiver built for payment events handles billing events with no
new integration.

Events are recorded **in the same database transaction** as the state change
they describe. A delivered event can never describe a state that was rolled
back, and each transition emits exactly once — retries of your endpoint
receive the same event, never a second one.

## Event catalog

| Event | Fires when |
| --- | --- |
| `InvoiceIssued` | A document is issued — numbered, legally real. |
| `InvoiceSent` | The collection link was created (`POST /invoices/{invoiceId}/send`). |
| `InvoicePaid` | The document settled — by hosted payment, matched bank transfer, or stored credit covering it in full. `paidVia` says which. |
| `InvoiceOverdue` | A sent document passed its due date unpaid. |
| `InvoiceVoided` | The document was cancelled before money moved. |
| `InvoiceWrittenOff` | Collection was abandoned. |
| `CreditApplied` | An issued invoice drew stored credit down. |
| `CreditDepleted` | That drawdown consumed the contract's last available credit in the invoice's currency — top up, or the next invoice asks the customer for cash. |

## Subscription lifecycle

| Event | Fires when |
| --- | --- |
| `BillingSubscriptionStarted` | A subscription was created on a contract. |
| `BillingSubscriptionActivated` | It became active — a trial converted, or a term began. |
| `BillingSubscriptionRenewed` | A term rolled over into the next one. |
| `BillingSubscriptionPastDue` | Collection failed, or a trial ended with no payment method. |
| `BillingSubscriptionRecovered` | It came back from past due. |
| `BillingSubscriptionPaused` | Billing is suspended; no invoices are raised while it is. |
| `BillingSubscriptionResumed` | Billing continues **on the original schedule** — the period is not restarted. |
| `BillingSubscriptionCancelScheduled` | A cancellation was requested and takes effect after its notice period. |
| `BillingSubscriptionCanceled` | The cancellation took effect. |
| `BillingSubscriptionExpired` | A fixed end date was reached. |

**Why the `Billing` prefix.** The unprefixed `Subscription*` events on this
same pipe — `SubscriptionCreated`, `SubscriptionCharged`,
`SubscriptionCancelled`, `SubscriptionPastDue` — describe **payment-link
recurring subscriptions**, a different object with its own lifecycle. Two
products, one word. Subscribing to those will not tell you anything about a
billing subscription or its contract; subscribe to the prefixed family
instead.

**One exception, and you have to know it: `SubscriptionTrialWillEnd`.** The
prefixed family has no trial-ending event — a billing subscription's trial
reminder is emitted under that unprefixed name instead, one day before the
trial ends, with a payload of its own:

```json
{
  "source": "billing",
  "subscriptionId": 15,
  "contractId": 74,
  "trialEnd": "2026-09-17",
  "amountMinor": 820000,
  "currency": "EUR"
}
```

`source` is how you tell it apart: `billing` on the shape above, `payment_links`
on the larger shape a payment-link subscription's own trial reminder carries. It
is the OpenAPI discriminator for the two, so a generated client picks the right
type from it. (`contractId` is present on the billing shape only and remains a
valid tell for a receiver written before `source` existed — a payment-link
subscription has no contract.) The Payments API's webhook catalog publishes both
under the one event name. **If you want a trial-ending warning for a billing subscription, you
must subscribe to the unprefixed event** — the prefixed family does not carry
one.

Metered-usage threshold alerts (`UsageAlertFired`) were already delivered on
this pipe and are unchanged.

## The delivery body

Every delivery — whatever fired — is an envelope with the event's payload
nested inside it. The four envelope fields are the same for every family:

```json
{
  "eventId": 918204,
  "eventType": "InvoicePaid",
  "sellerAccountUuid": "6f2a1c1e-6a1e-4f10-9f2b-9c1d0b3a7e55",
  "occurredAt": "2026-08-20T14:02:11Z",
  "payload": { }
}
```

`eventId` is the delivery's stable identity: deduplicate on it. `occurredAt`
is when the state changed, not when the delivery was attempted — a retry
repeats the original value. `sellerAccountUuid` is your Fynex account, never
your customer.

Every event is also published in the OpenAPI document under its top-level
`webhooks` key, so a generated client carries the body type rather than
`map[string]any`.

## Payloads

Invoice events carry the document's public identity and money facts — the
same fields the API serves, and nothing it does not:

```json
{
  "invoiceId": 4180,
  "invoiceNumber": "UK2607AA-2608AAB",
  "contractId": 42,
  "sellerCustomerId": 7,
  "origin": "usage",
  "status": "paid",
  "paidVia": "payment_link",
  "currency": "EUR",
  "grandTotalMinor": 12000,
  "collectibleMinor": 12000,
  "dueDate": "2026-08-15T00:00:00Z",
  "occurredAt": "2026-08-20T14:02:11Z"
}
```

Buyer name and email are deliberately absent — webhook bodies land in the
receiver's logs, and the single-invoice read serves them to a caller who
holds the key. Treat the event as the signal and `GET /invoices/{invoiceId}`
as the source of truth.

A subscription event carries the subscription's identity and where it landed:

```json
{
  "subscriptionId": 15,
  "contractId": 74,
  "status": "paused",
  "billingFrequency": "monthly",
  "currency": "EUR",
  "priceMinor": 820000,
  "currentPeriodStart": "2026-08-17T00:00:00Z",
  "currentPeriodEnd": "2026-09-17T00:00:00Z",
  "occurredAt": "2026-08-28T11:04:22Z"
}
```

The event type says what happened and `status` says where it landed; there is
no `previousStatus`. Nothing in the body identifies the customer — look them
up through the contract if you need to.

Credit events:

```json
{
  "contractId": 42,
  "invoiceId": 4181,
  "invoiceNumber": "UK2607AA-2608AAC",
  "currency": "EUR",
  "appliedMinor": 250000,
  "remainingMinor": 0,
  "occurredAt": "2026-09-01T00:05:00Z"
}
```

`remainingMinor` is the contract's available credit after the movement — it
is `0` on every `CreditDepleted` by definition.

## Delivery, signing, retries

Deliveries are HTTP POSTs to the webhook endpoints configured for your
account, signed with your endpoint's secret:

```
X-Fynex-Signature: sha256=<hex HMAC-SHA256 of the raw body>
X-Fynex-Timestamp: <unix seconds at which the delivery was signed>
```

Verify the signature against the **raw** request body before parsing, and
reject a delivery whose timestamp is far from your own clock — that is what
bounds replay of a body someone captured. Deliveries are retried with backoff
until your endpoint answers 2xx; your handler must therefore be idempotent.
Deduplicate on the envelope's `eventId`, which is stable across every retry of
the same event.

Endpoint registration, secret rotation and the retry schedule are the
Payments API's webhook machinery — see its **Webhooks** guide; nothing about
it is billing-specific.

## Polling still works

The polling guidance in **Workflows** remains valid and is the right tool for
reconciliation: a month-end close should read `GET /invoices` for the period
rather than reconstruct it from events. Webhooks are for the moment an
invoice being paid *unlocks something* — activating a seller, releasing a
listing, restoring access — where minutes of polling latency is real waiting.

---

# Code examples

Working snippets for the two pieces every integration needs — walking pages
and retrying correctly — plus a typed-client shortcut.

## Generate a client from the spec

The fastest path is not to hand-write a client at all. The spec is standard
OpenAPI 3.1:

```bash
curl -s "$FYNEX_API_BASE/openapi.json" -o fynex-billing.json

# TypeScript types
npx openapi-typescript fynex-billing.json -o fynex-billing.d.ts

# Python / Go / Java / … via openapi-generator
openapi-generator generate -i fynex-billing.json -g python -o ./fynex-billing-client
```

Generated models keep minor-unit amounts as integers and decimal quantities as
strings, which is what you want. If your generator maps `quantity` or
`taxRate` to a float, override it to a decimal type.

## Python: page through invoices

```python
import os
import time

import requests

BASE = os.environ["FYNEX_API_BASE"]  # e.g. https://api.fynex.ai/billing-api/v1
SESSION = requests.Session()
SESSION.headers["Authorization"] = f'Bearer {os.environ["FYNEX_API_KEY"]}'


def request(method, path, **kwargs):
    """One request with the retry policy: honour Retry-After on 429,
    back off on 5xx, never retry other 4xx."""
    delay = 1.0
    for attempt in range(6):
        response = SESSION.request(method, f"{BASE}{path}", timeout=30, **kwargs)

        if response.status_code == 429:
            # Retry-After is authoritative; retrying sooner just deepens the overage.
            time.sleep(int(response.headers.get("Retry-After", "1")))
            continue
        if response.status_code >= 500:
            time.sleep(delay)
            delay *= 2
            continue
        if not response.ok:
            # 400/401/403/404/422 — the request must change, so retrying is pointless.
            raise RuntimeError(f"{response.status_code}: {response.json().get('error')}")

        return response
    raise RuntimeError("giving up after repeated throttling or server errors")


def iter_invoices(**filters):
    """Yield every invoice, newest first, following the keyset cursor."""
    before_id = None
    while True:
        params = {"limit": 100, **filters}
        if before_id:
            params["cursor"] = before_id

        page = request("GET", "/invoices", params=params).json()
        for invoice in page["invoices"]:
            yield invoice

        if not page["hasMore"]:
            return
        before_id = page["nextCursor"]


outstanding = [
    inv for inv in iter_invoices(origin="usage")
    if inv["status"] in ("issued", "sent") and inv["collectibleMinor"] > 0
]
total_minor = sum(inv["collectibleMinor"] for inv in outstanding)
print(f"{len(outstanding)} open invoices, {total_minor / 100:.2f} outstanding")
```

The last line divides by 100 only because the example is EUR. Currencies have
different minor-unit scales — divide by the scale of the invoice's own
`currency`, or better, keep the integer and format at the edge.

## Node: collect on an invoice

```javascript
const BASE = process.env.FYNEX_API_BASE; // https://api.fynex.ai/billing-api/v1

async function call(method, path, options = {}) {
  for (let attempt = 0; attempt < 6; attempt++) {
    const response = await fetch(`${BASE}${path}`, {
      method,
      ...options,
      headers: {
        Authorization: `Bearer ${process.env.FYNEX_API_KEY}`,
        ...options.headers,
      },
    });

    if (response.status === 429) {
      const wait = Number(response.headers.get("Retry-After") ?? 1);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    if (response.status >= 500) {
      await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
      continue;
    }
    const body = await response.json();
    if (!response.ok) throw new Error(`${response.status}: ${body.error}`);
    return body;
  }
  throw new Error("giving up after repeated throttling or server errors");
}

// Safe to retry as-is: the invoice's durable link association makes repeated
// and simultaneous calls converge on the same payment link.
const { invoice, paymentLinkUrl } = await call("POST", `/invoices/${invoiceId}/send`);
console.log(`Invoice ${invoice.invoiceNumber}: ${paymentLinkUrl}`);
```

## Go: usage against plan limits

```go
type MetricUsage struct {
	MetricName    string `json:"metricName"`
	Used          string `json:"used"`          // decimal string
	IncludedUnits string `json:"includedUnits"` // decimal string
	CapQuantity   string `json:"capQuantity,omitempty"`
	CapMode       string `json:"capMode,omitempty"`
	PercentOfPlan string `json:"percentOfPlan,omitempty"`
	PeriodStart   string `json:"periodStart,omitempty"`
	PeriodEnd     string `json:"periodEnd,omitempty"`
}

type ContractUsage struct {
	ContractID int64         `json:"contractId"`
	Metrics    []MetricUsage `json:"metrics"`
}

func overageMetrics(ctx context.Context, client *http.Client, baseURL, key string, contractID int64) ([]MetricUsage, error) {
	req, err := http.NewRequestWithContext(ctx, http.MethodGet,
		fmt.Sprintf("%s/contracts/%d/usage", baseURL, contractID), nil)
	if err != nil {
		return nil, err
	}
	req.Header.Set("Authorization", "Bearer "+key)

	resp, err := client.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		var apiErr struct {
			Error string `json:"error"`
		}
		_ = json.NewDecoder(resp.Body).Decode(&apiErr)
		return nil, fmt.Errorf("usage snapshot: %d: %s", resp.StatusCode, apiErr.Error)
	}

	var usage ContractUsage
	if err := json.NewDecoder(resp.Body).Decode(&usage); err != nil {
		return nil, err
	}

	var over []MetricUsage
	for _, m := range usage.Metrics {
		// Decimal, not float: these quantities carry fractional precision.
		pct, err := decimal.NewFromString(m.PercentOfPlan)
		if err != nil || m.PercentOfPlan == "" {
			continue // no plan allowance configured for this metric
		}
		if pct.GreaterThan(decimal.NewFromInt(100)) {
			over = append(over, m)
		}
	}
	return over, nil
}
```

## Shell: download every PDF for a month

```bash
#!/usr/bin/env bash
set -euo pipefail

BASE="${FYNEX_API_BASE:?set FYNEX_API_BASE}"
AUTH="Authorization: Bearer ${FYNEX_API_KEY:?set FYNEX_API_KEY}"
cursor=""

while :; do
  url="$BASE/invoices?limit=100"
  [ -n "$cursor" ] && url="$url&cursor=$cursor"
  page="$(curl -sf -H "$AUTH" "$url")"

  # Every issued document renders, including void ones and credit notes —
  # they are part of the audit trail. Filter here if you only want live ones.
  echo "$page" | jq -r '.invoices[] | "\(.id) \(.invoiceNumber)"' |
    while read -r id number; do
      curl -sf -H "$AUTH" "$BASE/invoices/$id/pdf" -o "invoices/$number.pdf"
    done

  [ "$(echo "$page" | jq -r '.hasMore')" = "true" ] || break
  cursor="$(echo "$page" | jq -r '.nextCursor')"
  sleep 1  # stay clear of the per-seller rate limit while bulk-downloading
done
```

## Testing your integration

Point everything at a `sk_test_…` key while your account is still in demo
mode. Going live is two steps, not one: Fynex switches the account to live
mode, and you swap in an `sk_live_…` key. From that moment the test key no
longer authenticates (`401`), so make the key a configuration value rather
than a constant. The billing records themselves belong to the account — a
live key does not reveal a second, hidden dataset.

Worth exercising before you ship:

- A `404` path (a contract id that is not yours) — confirm you surface it as
  "not found" rather than crashing on a missing field.
- A `429` path — force it by looping requests, and confirm your client waits
  for `Retry-After` instead of hot-looping.
- A multi-page walk — seed more rows than your page size, or set `limit=1`,
  and confirm you follow `nextCursor` to the end.

---

# Contracts

A contract is the commercial agreement every other billing object hangs off:
subscriptions bill on it, credit is held against it, metered usage is priced
under it and every invoice names it. It belongs to one of your customers (a
`sellerCustomerId` from `POST /customers`) and bills in one currency for its
whole life — credit and invoices under it are never converted.

## Versions, not edits

A contract is a stable id plus an append-only history of **versions**. Nothing
is ever updated in place: every change — a status move, a new end date, a
different set of components — is a new version appended on top of the last,
and every earlier version stays readable. `GET /contracts` shows the current
version of each contract you own, with `version` saying how many there are.

That is what an amendment is: **a compare-and-swap on the version number**.
You send the `expectedBaseVersion` you last read; if the contract has moved on
since, the amendment answers `422` and you re-read before deciding again.
Two integrations amending the same contract can therefore never silently
overwrite each other.

## Status

`draft` → `active` → `suspended` ⇄ `active` → `closed`. A contract starts in
`draft`. `closed` is terminal: nothing about a closed contract can be amended.
A transition the state machine does not allow (anything out of `closed`, or
`draft` straight to `suspended`) answers `422`.

**Closing a contract does not cancel its subscriptions.** The status is a
record of the commercial relationship; no billing engine reads it, so a
subscription on a closed contract keeps renewing and keeps issuing invoices.
Cancel each one with `POST /billing-api/v1/subscriptions/{subscriptionId}/cancel`
FIRST, then close the contract.

## Endpoints

- `GET /billing-api/v1/contracts` — the current version of every contract you
  own, keyset-paged by contract id.
- `POST /billing-api/v1/contracts` — create one, in `draft`, for one of your
  customers. **`Idempotency-Key` is required**: the same key returns the
  contract the first call created (`200` instead of `201`); the same key
  answers `422`, naming the field, when the request differs in its
  `sellerCustomerId`, `currency` or the `lineItems` themselves — compared line by line on
  `componentType`, `componentConfig` and `quantity`, order-insensitively — or in the
  `startDate` or `endDate` as the key first created it. It also carries an EXTRA per-seller
  quota of its own — 20 create requests a rolling day by default (a refused or replayed request counts too), answered as `429`
  with `Retry-After` — bounding how fast one key can open contracts, each of
  which allocates a number from a sequence shared across sellers.
- `POST /billing-api/v1/contracts/{contractId}/amendments` — append a version:
  a status move, new dates, a replaced component set, or the counterparty's
  details as agreed. `expectedBaseVersion` is required and is the concurrency
  guard; there is no `Idempotency-Key`, because a repeat of a successful
  amendment fails the version check by construction. This one carries an EXTRA
  per-seller quota too — 200 amend requests a rolling day by default (a stale `expectedBaseVersion` counts too) — because
  every accepted amendment appends a version that can never be deleted.
- `GET /billing-api/v1/contracts/{contractId}/usage` and
  `GET /billing-api/v1/contracts/{contractId}/credits` — what has been metered
  and what stored value is held under the contract.

Both write quotas, and the invoice issue quota, **fail closed** — while the
limiter is unreachable they answer `503` with `Retry-After` and the write does
not happen; see [Errors → rate limiting](/billing-api/v1/docs/errors#when-the-write-quotas-fail-closed).

## Components

`lineItems` on a contract are its **components**: what the agreement says is
being sold, each with a `componentType`, a `quantity` (decimal string) and an
optional `componentConfig` the engine reads for that type. They are
snapshotted per version — an amendment either carries the current set forward
(omit `lineItems`) or replaces it whole (send the full new set; `[]` clears
it). There is no partial edit, for the same reason there is no partial edit
of anything else here: the version is the audit trail.

A contract may have no components at all. Its billing is then defined by the
subscriptions attached to it (`POST /contracts/{contractId}/subscriptions`)
and the metered prices set under it.

## What the seller key may not do

Contracts created through this API record no dashboard user as their author
(`createdBy` is `0`): the seller key is the actor, and the audit trail names
the key's seller account. Contract PDFs, tax profiles and the backoffice
review of a contract stay dashboard operations.

---

# Invoices

A billing invoice is an immutable, numbered document. The relational fields
you see in responses (totals, dates, status) mirror a frozen, schema-valid
payload snapshotted at issue time; the PDF renders from that snapshot.

## Lifecycle

`draft → issued → sent → paid`, with `overdue` for a sent document still
unpaid past its due date, and three corrective exits:

- `voided` — the document was cancelled before money moved (`voidedAt`,
  `voidReason`).
- written off — collection was abandoned (`writtenOffAt`, `writeOffReason`).
- credit note — a separate document (`invoiceType: "credit_note"`) naming the
  original in `originalInvoiceNumber`.

`paidVia` records how a paid document settled: `payment_link` (the card rail —
either the buyer visiting the hosted page, or an off-session charge on their
saved card when the seller has auto-collection enabled), `bank_transfer` (a
deposit on the collection account named on the document) or `credit` (stored
credit covered it in full at issue).

A document can therefore reach `paid` without you doing anything, and can
appear on `GET /invoices` without anyone creating it: whether terms and
metered usage are invoiced on a schedule, and whether saved cards are charged
off-session, are per-seller operator switches. See **Sandbox & testing** for
the switches themselves.

## Numbering

Every issued document carries TWO numbers, and they are not interchangeable.

`invoiceNumber` (`UK2607AB-2607AAC`) is the document's identity: unique across
every Fynex invoice family, allocated from the shared per-(agreement, month)
sequence, and **also the bank payment reference** — it is the only string a
buyer may quote on a transfer, and it is what `bankTransfer.paymentDescription`
returns.

`customerDocumentNumber` (`0000042`) is the document's position in that
customer's own series: cumulative for the life of the (seller, customer) pair,
never reset, and counted independently for each customer. Credit notes take the
next position like any other document, and a voided document keeps the one it
had. It is a convenience reference printed as "Your document no." — unique only
within the pair, so it is never a lookup key and never a payment reference.
Absent on documents issued before the series existed; those are not backfilled.

## Numbering

An invoice number is `<agreement>-<YYMM><order>`: your agreement number, a
dash, the issue month as `YYMM`, and a three-letter order within that month
(`AAA`, `AAB`, …) — for example `UK2607AA-2608AAB` is the second document
issued in August 2026 under agreement `UK2607AA`. The series is allocated
inside the issuing transaction, so it is gapless per month, and it is shared
with top-up invoices so the two document families can never collide. Numbers
are what `corrects` and `originalInvoiceNumber` reference, so store them
verbatim — do not parse meaning out of the order suffix.

`customerName` and `customerEmail` carry who the document was addressed to at
issue — taken from the frozen payload, so a customer later renaming themselves
does not rewrite an issued legal record. They are returned by the
single-invoice read and by `send`, and omitted from list rows.

## Endpoints

- `GET /billing-api/v1/invoices` — list, newest first, paged with
  `cursor`/`limit`. Filters: `contractId`, `sellerCustomerId`, `status`,
  `invoiceType` (`standard`, `credit_note`, `simplified`, `modified`),
  `origin` (`recurring`, `usage`, `milestone`, `project`, `one_time`, `adhoc`,
  `marketplace`; `subscription` is a deprecated alias of `recurring`),
  `corrects` (credit notes against an invoice number), `issuedFrom`/`issuedTo`
  (half-open date range).
- `POST /billing-api/v1/invoices` — compose, number and (by default) send a
  document in one call, behind a required `Idempotency-Key`. It is issued and
  immutable the moment the call answers `201`; the same key replays the
  document with `200` and no link, and a key whose request differs in its
  contract, customer, currency, `invoiceType`, `dueDate`, net line total or
  line count answers `422` naming the field. There are no drafts on this API:
  send explicit lines with `unitPriceMinor`. `invoiceType` accepts `standard`
  (the default), `simplified` and `modified`; **`credit_note` is refused with
  `400`** — a correction is raised against the document it corrects, which this
  request cannot express, and there is no `originalInvoiceNumber` field on it.
  Correct a mistake in the dashboard.
- `GET /billing-api/v1/invoices/{invoiceId}` — one invoice with its lines.
- `GET /billing-api/v1/invoices/{invoiceId}/pdf` — the rendered PDF.
- `POST /billing-api/v1/invoices/{invoiceId}/send` — materialize the
  collection instrument: creates the invoice's hosted payment link and returns
  the invoice together with `paymentLinkUrl`. **It emails your customer**
  whenever the document carries a buyer email; there is no per-request
  suppression in v1, so the first call is customer-facing. The invoice is
  itself the collection anchor, so retries and simultaneous calls return the
  one existing link and do not send another email — no idempotency header is
  needed. Not applicable (`422`) to bank-transfer documents, to documents
  outside `issued`/`sent`/`overdue` (a `draft`, or one already `paid`,
  `voided` or `written_off`), or to documents with nothing left to collect.

## Amounts

`grandTotalMinor` is the legal document total. `collectibleMinor` is what
collection asks the customer for: the grand total less `creditAppliedMinor`
(stored credit drawn down at issue).

`creditSettledMinor` reports only the part discharged by that stored credit —
it is **not** a payment total, and a card- or transfer-paid invoice reports
`0`. Neither amount changes when the invoice is paid: `status` and `paidVia`
are what tell you the outcome.

`outstandingMinor` is the one to age in an AR report. `collectibleMinor` is
frozen at issue and stays there, so it keeps asking for the full amount after a
credit note, a write-off or any other adjustment; `outstandingMinor` is derived
from the adjustment ledger on every read and reports what is genuinely still
owed (`0` for a voided document). It is omitted when the adjustment ledger is
unavailable — absence means **unknown**, not `0`.

---

# Subscriptions

A subscription is one recurring billing relationship on a contract. All date
fields are UTC calendar dates — billing runs on dates, not instants.

## States

`trial → active ⇄ past_due / paused → canceled | expired`

- `trial` — running a free trial until `trialEnd`. `trialEndBehavior` says
  which way it ends: `convert` (becomes a paying subscription) or `cancel`
  (lapses). `trialRequiresPaymentMethod` tells you whether a payment method
  must be on file first.
- `active` — billing normally within `currentPeriodStart…currentPeriodEnd`.
- `past_due` — a renewal charge failed. **No automatic retry runs**: recovery
  is your action or a dashboard operation. Treat this status as "act now",
  not as "Fynex is handling it".
- `paused` — billing suspended (`pausedAt`, optional auto-resume at
  `pauseEndsAt`).
- `canceled` / `expired` — terminal. A cancellation with notice keeps serving
  until `cancelEffectiveAt`.

## Price and plan

There is no separate plan object: the plan reference is
`priceMinor + currency + billingFrequency` (with `customUnit`/`customEvery`
for custom cadences). A scheduled downgrade appears as
`pendingPriceMinor`/`pendingPriceChangeAt` until the renewal pass applies it.

## Endpoints

Read:

- `GET /billing-api/v1/subscriptions` — list, newest first. Filter:
  `contractId`. Pages with `cursor`/`limit`, newest first.
- `GET /billing-api/v1/subscriptions/{subscriptionId}` — one subscription.

Create:

- `POST /billing-api/v1/contracts/{contractId}/subscriptions` — a new
  subscription on a contract you own. **`Idempotency-Key` is required** (1–128
  characters, `A–Z a–z 0–9 _ . : -`): the same key always returns the
  subscription the first call created (`200` instead of `201`), whatever the
  body of the retry; use one key per subscription you intend to create. Keys
  are scoped to your seller account — the same key on a different contract
  answers `422`; a key under a billing-engine prefix (`proration:`, `redeem:`,
  `subscription:`, …) answers `400`. Body: `frequency` (`daily`, `weekly`,
  `bi_weekly`, `monthly`, `quarterly`, `semi_annual`, `annual`, `custom` with
  `customUnit`/`customEvery`), `priceMinor` + `currency` (the contract's),
  `startDate` (up to a year in the past), optional `anchorDate`, `trialEnd` +
  `trialEndBehavior` (`convert`/`cancel`), `autoRenew` (default `true`; an
  explicit `false` needs `endDate`, and `endDate` is refused otherwise),
  `noticePeriodDays` (0–365), `prorationPolicy`
  (`by_day`/`full_period`/`next_period` — selects what an immediate
  `change-plan` does once the proration engine is enabled: prorate the
  unserved remainder, bill the whole current period at the new price with the
  elapsed days included and no adjustment, or keep the old price until the
  next period. Inert while the engine is off, which is the default. Where
  invoice binding is enabled for the environment, the recorded proration is
  applied to the term's next invoice).

```bash
curl -X POST "$FYNEX_API_BASE/contracts/42/subscriptions" \
  -H "Authorization: Bearer $FYNEX_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"frequency":"monthly","priceMinor":9900,"currency":"EUR","startDate":"2026-10-01","noticePeriodDays":30}'
```

Lifecycle, all `POST /billing-api/v1/subscriptions/{subscriptionId}/…`:

| Action | Body | From | Effect |
| --- | --- | --- | --- |
| `cancel` | — | `trial`, `active`, `past_due`, `paused` | Sets `cancelRequestedAt`; serves until `cancelEffectiveAt` (notice period) or term end. Terminal. |
| `pause` | `{"pauseUntil": "YYYY-MM-DD"}` optional | `active` | Suspends billing; `pauseEndsAt` when a date was given. Longer than the seller's pause policy → `422`. |
| `resume` | — | `paused` | New term from today; the pause is not billed. |
| `end-trial` | — | `trial` | Converts now per `trialEndBehavior` / `trialRequiresPaymentMethod`. |
| `change-plan` | `{"priceMinor": 12900, "currency": "EUR", "atTermEnd": true}` | `active` | Scheduled (`pendingPriceMinor`) or immediate. `atTermEnd: true` always schedules; with `false` the subscription's `prorationPolicy` decides while the proration engine is on — `next_period` keeps the old price for the rest of this period and applies the new one from the next, `by_day` applies it now and posts an adjustment for the unserved remainder, `full_period` applies it now and bills the whole current period at the new price, elapsed days included, with no adjustment. Same price, or a change already pending → `422`. Currency cannot change. |

Every action returns the updated subscription. A request the current state
cannot take — pausing a trial, resuming an active subscription, cancelling
twice — answers `422` with the reason; so does a lost race against the
lifecycle pass (`subscription changed concurrently; re-read it and retry`).
`404` means the subscription is not yours. Marking past-due or recovered is
the collection loop's job and has no public route.

---

# Usage

Metered usage is ingested by your systems (or Fynex connectors), aggregated
per contract, metric, and billing period, and rated into usage invoices at
period close. This API exposes the aggregated view.

## Endpoints

- `GET /billing-api/v1/contracts` — the contracts visible to your key, the
  entry point for every per-contract read. Paged by ascending contract id:
  while `hasMore` is true, pass the returned `nextCursor` back as `cursor`.

```json
{
  "contracts": [
    {
      "contractId": 42,
      "contractNumber": "UK2607AA",
      "version": 1,
      "sellerCustomerId": 7,
      "currency": "EUR",
      "status": "active",
      "startDate": "2026-01-01",
      "customerName": "Ada Lovelace",
      "customerCompanyName": "Harbour Group BV"
    }
  ],
  "hasMore": false
}
```

- `GET /billing-api/v1/contracts/{contractId}/usage` — the current open
  billing periods of every metric on the contract:

```json
{
  "contractId": 42,
  "metrics": [
    {
      "metricName": "api_calls",
      "used": "10250",
      "includedUnits": "10000",
      "capQuantity": "50000",
      "capMode": "hard",
      "percentOfCap": "20.5",
      "percentOfPlan": "102.5",
      "periodStart": "2026-08-01",
      "periodEnd": "2026-08-31"
    }
  ]
}
```

`used` counts everything metered this period; `includedUnits` is the plan
allowance; `capQuantity`/`capMode` describe the limit policy when one is
configured. Quantities are decimal strings. An unknown contract id answers
`404`; a real contract with nothing metered answers `200` with an empty
`metrics` array.

> [!IMPORTANT]
> **This is a live reading, not the figure the customer will be invoiced.**
> The period is still open, so `used` moves with every event that arrives —
> including events for work already done that reach us late. It is also
> pre-invoice: allowances, credits, discounts and rounding are applied when the
> period closes and the invoice is produced, and none of them are reflected
> here.
>
> Show it to a customer as "usage so far", never as an amount owed, and
> reconcile against the invoice the period produced rather than against this
> endpoint. A dashboard that quotes this number as the bill will disagree with
> the bill.

This endpoint reads a meter; something has to fill it. Writing usage —
registering a metric, pricing it, and sending events — happens under
`/billing-api/v1/usage`, with the same seller secret key, and is documented in
full under **Usage ingestion**. In short: `POST /billing-api/v1/usage/metrics`
to declare the meter, `PUT
/billing-api/v1/usage/contracts/{contractId}/metrics/{metricName}/price` to
price it, and `POST /billing-api/v1/usage/events` (or `:batch`, or `/csv`) to
report consumption.

## What this endpoint keeps, and for how long

**This is a meter, not a history API.** It answers with the contract's
**currently open** billing periods — one entry per metric with a limit policy
or metered usage. It has no date range and no paging, and a period that has
closed is no longer in the response. If you need consumption over time, record
what you read while the period is open, or take it from the invoice the period
produced: the invoice is the durable record of what was billed.

**Stored events are retained indefinitely.** Nothing prunes them — there is no
retention window on ingested usage and no job that deletes it, so an
idempotency key you used a year ago is still recognised and resending that
event is still a no-op. Two practical consequences:

- Idempotency keys must stay unique for the lifetime of your integration, not
  just for a period. Derive them from something durable — a row id, an export
  digest — rather than from a timestamp that repeats.
- Correcting metered history is done by issuing a correction against the period
  (see **Usage corrections**), never by deleting events. There is no delete.

Documents are the exception: invoices and credit notes carry a statutory
retention period per jurisdiction, which is a legal minimum on how long they
are kept, not a window after which this endpoint stops answering.

---

# Credits

Stored value is a capability your deployment switches on. While it is off,
every endpoint below answers `501` with `billing credits are not enabled` —
and that is the honest answer, because with it off the billing engine does
not draw credit into invoices at all, so any balance shown would never be
consumed.

Credits are stored value held against a contract — customer prepayments,
promotional grants, goodwill. Balances are derived from an append-only
ledger; drawdown happens automatically when an invoice is issued against a
contract holding credit (visible on the invoice as `creditAppliedMinor`).

## Endpoints

- `GET /billing-api/v1/credits` — your balances across all contracts, one row
  per currency and credit type:

```json
{
  "balances": [
    {"currency": "EUR", "creditType": "purchased", "balanceMinor": 250000, "isLiability": true}
  ]
}
```

`creditType` is one of `promotional`, `purchased`, `manual`, `gift`,
`enterprise`, `ai_token`, `marketplace` or `proration`. `isLiability` marks
the paid-for types (`purchased`, `enterprise`, `proration`) — unearned revenue
you owe as service. Those never expire; granted credit may. `proration` is
minted by the engine rather than granted by you: when a mid-term subscription
amendment credits your customer more than the invoice it lands on can absorb,
the remainder becomes a `proration` lot — money the customer already paid for
service not rendered — and the next document draws it down.

- `GET /billing-api/v1/contracts/{contractId}/credits` — one contract's
  balances (always complete) plus a page of its ledger history. `limit` sets
  the page size (1–100, default 20); while `hasMore` is true, pass the
  returned `nextCursor` back as `cursor` to walk older entries:

```json
{
  "balances": [ ... ],
  "hasMore": true,
  "nextCursor": 1180,
  "nextBeforeId": 1180,
  "entries": [
    {
      "id": 1201,
      "kind": "topup",
      "creditType": "purchased",
      "signedDeltaMinor": 250000,
      "currency": "EUR",
      "invoiceId": null,
      "reason": "annual prepayment",
      "occurredAt": "2026-08-01T09:30:00Z"
    }
  ]
}
```

Entries are newest-first. `kind` is `topup`, `deduction`, `expiry` or
`reversal` — the last one returns a deduction to the customer when the invoice
it funded is cancelled. `signedDeltaMinor` is positive for `topup` and
`reversal`, negative for `deduction` and `expiry`, and `invoiceId` links a
deduction (and the reversal that undoes it) to the document it funded.

- `POST /billing-api/v1/contracts/{contractId}/credits/top-up` — grant a
  credit lot. This is the only way credit enters the ledger; `deduction`,
  `expiry` and `reversal` rows are the engine's and have no public route.

```bash
curl -s -X POST "$FYNEX_API_BASE/contracts/42/credits/top-up" \
  -H "Authorization: Bearer $FYNEX_API_KEY" \
  -H "Idempotency-Key: 3f0b6a1e-9c1d-4f10-9f2b-6f2a1c1e6a1e" \
  -H "Content-Type: application/json" \
  -d '{"creditType":"purchased","amountMinor":250000,"currency":"EUR","reason":"annual prepayment"}'
```

`Idempotency-Key` is required, and here the body **is** compared: the same key
with a different contract, `amountMinor` or `currency` answers `422` instead of
returning the first grant, because a top-up that never happened must not look
like one that did. A matching replay answers `200` with the original entry; the
first call answers `201`.

`currency` must equal the contract's own — credit is never converted. An
`expiresAt` is allowed only on granted credit: `purchased` and `enterprise`
were paid for, and money someone paid must not evaporate on a calendar date.
`sellerCustomerId` is optional attribution and must name one of your customers
(`POST /billing-api/v1/customers`); the contract remains the balance anchor.

Correcting a grant is not an edit — the ledger is append-only. Contact support
for a correcting entry.