Pricing & plans 201: Usage billing
Implement metered and consumption-based usage billing in Recurly. Learn how to configure usage-type add-ons, log records via the API, select aggregation strategies, and handle billing in arrears.
Acquire · Pricing & Plans 201
Usage billing
Charge subscribers for what they actually consume — API calls, messages, gigabytes stored — billed in arrears at the end of each billing period. Usage billing requires an API integration: this is not a UI-only configuration.
Navigation Menu
Navigate Home
Usage billing
How usage billing works in Recurly
Usage billing in Recurly works through usage-type add-ons attached to a plan. Your system logs consumption events to Recurly via the API throughout the billing period. When the period closes, Recurly aggregates those records and charges the subscriber based on what was logged — billed in arrears on their next invoice.
The base subscription renews on its regular schedule. Usage charges appear as a line item on that same invoice, covering the prior period's consumption. The first invoice does not include usage add-ons at all. From the second billing period onward, a usage line item appears on every invoice — even if usage was zero for that period.
Usage billing is not a UI-only configuration. Your system must log consumption records to Recurly's API throughout each billing period. Without those API calls, Recurly has nothing to bill. Align your engineering team on the logging architecture before configuring usage add-ons in your account.
Cumulative vs. last recorded
The aggregation strategy determines how Recurly calculates the billable amount from the usage records logged during a period. Choose based on what your usage metric actually represents.
Sum of all records in the period
Every usage record logged during the billing period is added together. A subscriber who logs 1 GB/day for 30 days is charged for 30 GB at the end of the period.
Use for: API calls, messages sent, transactions processed, data transferred — any metric where each event represents real consumption that should be billed.
Most recent record only
Only the final usage record logged before the period closes is used for billing. A subscriber who had 50 seats for most of the month, then reduced to 40 seats, is billed for 40.
Use for: seat count, active users, storage level — any metric representing a current state rather than accumulated activity.
If you change a usage add-on's aggregation strategy (cumulative to last recorded, or vice versa), the change applies only to subscriptions created after the switch. To update the strategy on an existing subscription, remove the add-on from that subscription, update the plan, and re-add it.
Setting up usage billing
Usage billing has two parts: the plan and add-on configuration in Recurly, and the API integration that logs usage records from your system. Both must be in place before live billing works correctly.
Create or edit a plan
Navigate to Configuration → Plans and create a new plan or open an existing one. The plan defines your base subscription charge and billing interval. Usage charges are added separately as an add-on in the next step.
Add a usage-type add-on
Within the plan, add a new add-on and set its type to Usage. Define the measured unit (e.g., "API calls", "GB", "messages"), set the pricing model — fixed per unit, percentage of logged amount, or a quantity-based model (tiered, volume, or stairstep) — and set the billing timing to in arrears.
Choose your aggregation strategy: cumulative sums every usage record logged in the period; last recorded charges based only on the most recent record. Cumulative is the right choice for consumption-based metrics. Last recorded suits metrics like seat count or storage level where you bill for the current state, not total activity.
Log usage records via the API
Your system sends usage records to Recurly's Create Usage endpoint throughout the billing period. Each record specifies the subscription, the add-on code, the amount of usage, and an optional timestamp. Records can be logged in real time or batched — Recurly aggregates them at billing time regardless.
Usage records can be updated after logging if you need to correct a value for tiered or flat models (not for volume or stairstep pricing models). Once the billing period closes and the invoice is generated, usage records for that period are locked.
Verify in sandbox before going live
In your Recurly sandbox, create a test subscription with the usage add-on, log sample usage records via the API, and advance the billing date to trigger an invoice. Confirm that the usage line item on the invoice reflects the correct aggregation and pricing. Test both the cumulative path and the no-usage path — a subscriber who logged zero usage should receive a $0 usage line item, not a missing one.
Usage-based add-ons appear in Recurly Checkout, but their cost is excluded from the displayed order total — because the actual charge depends on consumption that hasn't happened yet. Subscribers see the pricing structure (e.g., "$0.01 per API call") but not a projected total. Set expectations with your subscribers at signup about how usage charges will appear on their first invoice.
Planning a usage billing implementation?
Bring your usage billing architecture questions to Global Office Hours — aggregation strategy, logging frequency, pricing model selection, and sandbox testing are all common topics our CSMs can help you think through before your engineering team starts the integration.
Register for Office Hours →