Contracts and usage
Products with a price model, contracts that bill per cycle, and the usage your product reports.
For customers who pay every month, quarter or year: describe what you sell once as products, put them in a contract per customer, and report usage. AlphaCount bills each cycle — in advance for the period to come, usage and overage for the period that ended — and issues, sends and dunns those invoices like any other.
Products
PUT /products/by-ref/{source}/{external_ref}:
{
"name": "1 million tokens",
"unit_price_net": "40.00",
"vat_rate": 19,
"unit": "Paket",
"kind": "usage",
"pricing_model": "per_unit",
"billing_interval": "month",
"billing_timing": "arrears"
}| Field | Values |
|---|---|
kind | base_fee, seats, usage, credits, sla, service |
pricing_model | flat, per_unit, tiered_volume (all units at the tier reached), tiered_graduated (each tier at its price), package |
price_tiers | for the tiered models: [{ "from": 0, "to": 1000, "unit_price": "0.05" }, …] |
billing_interval | one_off, month, quarter, year |
billing_timing | advance (the coming period) or arrears (the period that ended) |
included_quantity, overage_unit_price | a quota per cycle, and what each unit beyond it costs |
A combination that does not add up — tiers without a tiered model, say — is 422 with a pricing.* code.
Contracts
PUT /contracts/by-ref/{source}/{external_ref}:
{
"customer": { "source": "myapp", "external_ref": "school-7" },
"name": "Learning platform",
"start_date": "2026-01-01",
"billing_interval": "month",
"invoice_mode": "issue_send",
"items": [
{ "ref": "seats", "product_ref": "seat", "quantity": 10 },
{ "ref": "tokens", "product_ref": "tokens", "quantity": 0 },
{ "ref": "sla", "product_ref": "sla" }
]
}invoice_mode:draft(a person reviews each invoice),issue, orissue_send.billing_starts_on: when AlphaCount starts billing — for a running contract you move over.- Each item has your
ref. A laterPUTchanges an item's quantity from the next cycle, adds new items and ends the ones you left out after the current cycle. An item's agreed price stays frozen. - While the contract is a draft, everything is replaced. Once it runs, interval and start are fixed
(
409 contract.terms_frozen), and arefkeeps its product (409 contract.item_product_changed). - There is no proration: a change applies from the next cycle.
GET /contracts/by-ref/… returns the contract with its items, next_billing_date, usage_open_from and every
cycle with its invoice.
Usage
POST /contracts/by-ref/{source}/{external_ref}/usage, up to 500 records per call, all or nothing:
{
"records": [
{ "item_ref": "tokens", "quantity": 1500, "occurred_on": "2026-01-10", "external_ref": "u-1" },
{ "item_ref": "tokens", "quantity": 500, "occurred_on": "2026-01-20", "external_ref": "u-2" }
]
}Each record's external_ref is stored once; the answer counts recorded and duplicates, so resending a batch is
safe. Usage before usage_open_from has been billed already and is refused (422 contract.usage_period_closed, with
open_from and the references) — it would reach no invoice. A draft or ended contract takes no usage
(409 contract.not_active).
A metering service needs only the scope partner:usage:write.
The invoices
The invoices of a contract are API invoices like any other: GET /invoices?contract_ref=…, the
invoice webhooks, cancellation.