Usage-based billing

Usage-based billing charges a subscriber for the calls they make. Apiable counts matching calls from your gateway's access logs, reports them to Stripe, and Stripe bills the metered total at the end of the billing cycle. It applies to the volume, graduated, and flat-fee plus overage pricing models.

What is usage-based billing in Apiable?

It charges a subscriber for usage instead of, or on top of, a fixed fee. Apiable counts each matching call from your gateway logs and reports the total to a Stripe meter. Stripe bills it on the plan's price when the cycle closes.

Three pricing models are metered: Usage-based - Postpaid - Volume Pricing, Usage-based - Postpaid - Graduated Pricing and Flat-fee - Upfront - Plus Overage. The plain Flat-fee - Upfront - Subscription Plans model bills a fixed price and counts nothing.

What do you need before usage counts?

Four things, all required. Without any one of them, the plan counts nothing. The Monetization tab names the first three when they are missing.

When you pick Apiable - API Calls, the tab reminds you: "Apiable is selected: Please ensure your API Gateway Logs are Connected."

Why does usage-based billing need gateway logs?

Apiable is not in your request path, so it never sees a call directly. It counts usage from the access log records your gateway delivers. A call is billable only once its log record reaches Apiable.

How does Apiable decide which calls to bill?

Each price can carry matching criteria. Until you add any, the price counts every call on the plan. Once it has criteria, a call counts when it matches at least one of them. Within one criterion, every condition you set must match.

You set them under Set the API Matching Criteria on the price, which the dashboard marks as Alpha. Add additional criteria opens the Matching Criteria dialog. A new criterion starts as All APIs, response code 2xx, and methods GET, PUT, POST and DELETE, which you can change.

Leave a condition out and it does not restrict anything. The Where clause in the dialog previews the criterion.

Keep at least one criterion on a price once you have added criteria. While a price has criteria, Bill Processing is locked to Apiable - API Calls; remove the criteria first to change it.

Can you bill tokens or your own units?

Yes. A flat-fee plus overage plan can bill tokens with Apiable - Tokens. For any other unit, choose Customer - Own Billing Units, name the unit in Billing Unit, and report usage yourself with the API.

• Apiable - Tokens is offered only on Flat-fee - Upfront - Plus Overage. Apiable totals the token counts in your gateway's token logs every hour and reports them to Stripe. On AWS, token logs use a separate stream, described in Enable usage logs on AWS API Gateway.
• Customer - Own Billing Units turns off counting from gateway logs for the plan. Billing Unit defaults to call, and only this option lets you rename it, for example to record. See Report usage with the API.

Matching criteria apply only to Apiable - API Calls.

How does usage flow to Stripe?

A scheduled billing run reads the new log records, applies each price's matching criteria, sums the matching calls per subscription, and reports the total to Stripe. Stripe bills the metered amount on the plan's price when the billing cycle closes.

1. A subscriber calls your API, and your gateway delivers the access log record to Apiable.
2. Apiable ingests delivered log files about once an hour.
3. The billing run, also about once an hour, applies each price's matching criteria and sums matching calls per subscription.
4. Apiable reports each sum to the subscription's Stripe meter.
5. Stripe bills the metered total when the billing cycle closes.

Allow one to two hours between a call and the usage appearing in Stripe. The subscription's page in the dashboard notes that there is a delay before the data is processed.

Troubleshooting

Match what you see to the fix.

Where to next