Billing API Changelog

Dated changes to the public contract, and how long a major version is supported.

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:

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.