Report usage with the API

You report usage to Apiable with a POST to /api/subscriptions/usage on your portal's Platform API endpoint. The body names the subscription and carries the quantity of new usage. Apiable records it on the subscription's Stripe meter, and Stripe bills the metered total when the billing cycle closes.

When do you report usage with the API?

When the plan's Bill Processing is Customer - Own Billing Units. Then Apiable does not count usage for you: you count it in your own systems and report it. With Apiable - API Calls, Apiable counts calls from your gateway logs, and a report would add to that count.

Reporting applies to subscriptions on metered prices: Usage-based - Postpaid - Volume Pricing, Usage-based - Postpaid - Graduated Pricing and Flat-fee - Upfront - Plus Overage. See Usage-based billing for how Apiable counts usage from gateway logs.

How do you report usage with the API?

Get an access token, then POST a JSON body to /api/subscriptions/usage on your Platform API endpoint, https://your-portal.api.apiable.io. Send increment with the usage that is new since your last report.

1. Exchange your Platform API client ID and secret for an access token at https://developer.apiable.io/api/oauth2/token.
2. POST the report to https://your-portal.api.apiable.io/api/subscriptions/usage with Authorization: Bearer <token> and Content-Type: application/json.
3. Read the response. A 200 means the usage was recorded.

What goes in the request body?

Identify the subscription with subscriptionId or integrationId, and send a quantity greater than 0. Leave the rest out unless the notes below apply to you.

Should you send increment or set?

Send increment, which is the default, with only the usage that is new since your last report. Do not send set. On subscriptions billed by usage, set does not replace the running total, so it cannot correct or restate a total.

What does a request look like?

First get a token, then send the report. This example adds 25 units to one subscription.

curl -X POST "https://developer.apiable.io/api/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d client_id="$APIABLE_CLIENT_ID" \
  -d client_secret="$APIABLE_CLIENT_SECRET"

Use the access_token from the response:

curl -X POST "https://your-portal.api.apiable.io/api/subscriptions/usage" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2024-09-25" \
  -d '{
    "subscriptionId": "664f1c2a9b1e4a0012ab34cd",
    "quantity": 25,
    "action": "increment"
  }'

The dashboard shows the same call for a subscription on a volume or graduated plan with Customer - Own Billing Units. Open the subscription and choose Show API call example.

What does Apiable do with the report?

Apiable checks the body, finds the subscription, and records the quantity on the subscription's Stripe meter. It returns 200 with a summary of what it recorded. Stripe adds the report to the period's total and bills it when the billing cycle closes.

The response carries subscriptionId, usageReportId, the id Stripe gave the report, and usageData, which echoes the quantity, time and action that were recorded. For volume and graduated plans, the subscription's page in the dashboard shows the running figure as Total reported consumption for the current period.

Troubleshooting

Match the response to the fix.

Where to next