Overview
The API settles the usage chargeback after a billing period closes successfully and makes the invoice available as a PDF.
Split chargeback
For a regulated internal cost allocation - such as a cross-charge between two business units - the receiving unit's share must not exceed the owning unit's share. The API validates this when a settlement is created and otherwise responds with 422 and code: "chargeback_not_permitted".
Check the same condition already on the deployment record - that's where the chargeback rate advertised in the catalog entry lives. A settlement that deviates from the advertised rate is hard to defend in a dispute.
Assessment basis
| Usage type | Basis |
|---|---|
metered | token/request usage recorded for the billing period |
subscription | monthly seat or budget allocation |
committed_use | annual committed spend, prorated monthly |
Payments
POST /settlements/{id}/payments also records partial payments. The status only moves to paid once the sum of payments reaches the gross amount; until then it stays partially_paid. That keeps what's outstanding visible without extra accounting logic.
Upfront calculation
POST /chargeback/calculator runs a chargeback calculation without creating anything. That's the right call for budget conversations and for the chargeback rate shown in the catalog entry.
Required scope
All calls require chargeback-settlement:read. Write operations are deliberately bound to the same role, because settlements should only ever be created by finance.