# Billing API Changelog

This is the public change record for the Billing API. Billing follows
Fynex's shared public API lifecycle policy: Payments and Billing both support
a public major version for at least 12 months after its successor is generally
available, and both give at least 90 calendar days' notice before removing a
public contract.

## 2026-10-19

### Changed: `includedUnits` on contract usage is the billed allowance

`GET /billing-api/v1/contracts/{contractId}/usage` now reports, as
`includedUnits`, the `allotment.includedUnits` of the metric price effective
for the period — the allowance the period close rates with — instead of the
limit policy's included units. `percentOfPlan` follows it. The backoffice
GraphQL usage view reports the same value.

What changes for an integration that reads the field:

| Metric | Before | Now |
| --- | --- | --- |
| Priced, allotment 10 000, limit policy 0 | `includedUnits: "0"`, no `percentOfPlan` | `includedUnits: "10000"`, `percentOfPlan` against 10 000 |
| Priced, allotment 0, limit policy 10 000 | `includedUnits: "10000"`, `percentOfPlan` against 10 000 | `includedUnits: "0"`, no `percentOfPlan` — every unit is billed |
| Not priced yet, limit policy 10 000 | `includedUnits: "10000"` | unchanged |

If you compute overage or alerts from `includedUnits`, the new value is the
one your invoices are rated with; the limit policy's cap is still reported as
`capQuantity`.

### Fixed: pausing a subscription needs no body

`POST /billing-api/v1/subscriptions/{subscriptionId}/pause` with no request
body pauses until resumed, as `{}` always did, instead of answering `400`.

## 2026-09-18

### Changed: metering routes under `/billing-api/v1` accept secret keys only

`/billing-api/v1/usage/*` now applies the same credential rule as every other
operation under the Billing prefix: only `sk_test_…` / `sk_live_…` secret keys
authenticate, and any other bearer value answers `401`. Before this date those
routes also accepted the older prefix-less seller token. Nothing changes for
integrations that already send a secret key, which is what every guide has
documented since the prefix was published. The legacy `/usage/v1/*` routes are
unchanged and continue to accept the credentials they always did.

### Fixed: webhook documentation

The Billing webhook pages described the signature as an HMAC over the raw body
and deliveries as "retried until 2xx". The signature has always been computed
over `<X-Fynex-Timestamp>.<raw body>`, only a `200` counts as delivered, and a
delivery is attempted at most 3 times. The documentation now says so; no
delivery behaviour changed.

## 2026-09-13

### Deprecated: `origin=subscription` query alias

`origin=subscription` is a deprecated alias for `origin=recurring` on
`GET /billing-api/v1/invoices`. Notice date: 2026-09-13. The legacy alias is
still accepted and returns the same invoice rows as `origin=recurring`, but it
is no longer produced for newly created invoices. Update integrations to use
`origin=recurring`.

The planned removal date is 2026-12-13, providing 91 calendar days' notice,
which is at least 90 calendar days. This is a **query-value deprecation**, not
an HTTP operation retirement. An OpenAPI `deprecated: true` marker applies to
an operation, parameter, field or schema; this individual enum-like query
value cannot be represented by an operation-level marker. The public changelog
entry is therefore the applicable value-level deprecation signal. Do not mark
the whole `origin` query parameter deprecated, and do not expect
`Deprecation` or `Sunset` response headers for this query value.