Monetization
Report usage with the API
Report usage to Apiable with a POST to a subscription's usage_records endpoint. Send a quantity, a timestamp inside the current billing period, an optional lookup key, and an increment or set action.
You report usage to Apiable by sending a POST to a subscription's usage_records endpoint with a Bearer token. The body carries the quantity to record, a timestamp inside the current billing period, an optional lookup key, and whether to add to or replace the period's usage. Use this when you meter a custom unit or count usage outside your gateway logs.
How do you report usage with the API?
Send a POST to the subscription's usage_records endpoint with a Bearer token and a JSON body. The body sets the quantity, a timestamp inside the current billing period, an optional lookup key, and an action of increment or set.
/api/v1/subscriptions/{subscriptionId}/usage_records This public path maps to the subscriptions usage_records route, which records usage against one subscription by its id. Confirm the exact host and version prefix for your portal before you call it; the route segment is subscriptions/{subscriptionId}/usage_records.
What goes in the request body?
Four fields. Only quantity and timestamp are required. The action defaults to increment, and the lookup key is only needed when a subscription has more than one active price.
| Field | Required | Type | What it is |
|---|---|---|---|
| quantity | Yes | Integer | The number of units to record. Must be greater than 0. |
| timestamp | Yes | Integer | The time of the usage, in Unix seconds. Must be within the current billing period. |
| lookupkey | No | String | Targets a specific price when the subscription has several active prices. Set on the plan's Monetization tab. |
| action | No | String | increment to add to the period's usage, or set to replace it. Defaults to increment. |
What is the difference between increment and set?
increment adds the quantity to the usage already recorded for the current period. set replaces the recorded usage with the quantity you send. The action defaults to increment. Any other value is rejected with a 400.
| Action | Effect | Use it when |
|---|---|---|
| increment | Adds the quantity to the period's running total. | You report each batch of usage as it happens. |
| set | Overwrites the period's total with the quantity. | You report a single authoritative total for the period. |
What does a request look like?
A minimal request increments usage by one for a subscription, timestamped now, in the current period.
curl -X POST "https://{portal}/api/v1/subscriptions/{subscriptionId}/usage_records" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"quantity": 1,
"timestamp": 1700733060,
"lookupkey": "gandalf",
"action": "increment"
}'What does Apiable do with the report?
Apiable validates the body, then records the usage against the subscription. It rejects a quantity of 0 or less, and any action other than increment or set, with a 400. Valid reports are added to or set on the subscription's usage for the current period, and Stripe bills the metered total when the cycle closes.