Set up a credit-based pricing model

Charge customers for pre-purchase credits.

Credits allow you to offer a fixed, monetary amount of usage across your usage-based products. This model works well when you want to give customers upfront predictability while aligning revenue directly to usage. For example, if you sell an API that processes images and cloud storage, a customer might buy 100 USD of credits at the start of the month. They can spend any combination of API usage and cloud storage up to the monetary amount, and pay an overage charge for either service at the end of the month if they exceed 100 USD of usage.

Credits apply indiscriminately across meters. To set specific limits on your various consumption based products,(for example 100 API requests and 3GB’s of storage) use the flat fee and overage model.

What you’ll build

In this guide, build the following subscription for a fictional company called Alpaca.ai, which provides LLM. They charge customers at the following rates:

Credits	Fee
Per user	10 USD

Usage	Fee
Input token	0.03 USD per token
Output token	0.05 USD per token

Create a meter

Meters specify how to aggregate meter events over a billing period. Meter events represent all actions that customers take in your system (for example, API requests). Meters attach to prices and form the basis of what’s billed.

For the Alpaca AI example, meter events are the number of input and output tokens a customer uses in a query. The meter is the sum of tokens over a month. In this example. you create a meter for each token type.

You can use the Stripe Dashboard or API to configure a meter. To use the API with the Stripe CLI to create a meter, get started with the Stripe CLI.

On the Meters page, click Create meter.
On the Create meter page, do the following:
- For Meter name, enter the name of the meter to display and for organization purposes. For the Alpaca AI example, enter “Alpaca AI Input tokens.”
- For Event name, enter the name to display in meter events when reporting usage to Stripe. For the Alpaca AI example, enter “alpaca_ai_input_tokens.”
- Set the Aggregation method in the dropdown:
  - For the Alpaca AI example, select Sum. This will sum the values reported (in this example, number of tokens a customer uses) to determine the usage to bill for.
  - Choose Count to bill based on the number of events reported.
  - Choose Last to bill based on the last value reported.
  - Use the preview pane to set example usage events and verify the aggregation method.
- Click Create meter.
- To create a meter for output tokens, repeat the previous steps and set the meter name to “Alpaca Output Tokens” and the Event name to “alpaca_ai_output_tokens.”
- (Optional) Under Advanced settings, specify the Dimensions that you want to tag your usage data with. To generate granular segment specific alerts, or to granularly price usage based on a combination of attributes, submit your usage data with dimensions that are populated for analytics and reporting. Some example dimensions are LLM model, token type, region, and event type.

Create a pricing model

Use the Stripe Dashboard or API to create a pricing model that includes your Products and their pricing options. Prices define the unit cost, currency, and billing period.

For the Alpaca AI example, you create two products each with a meter billed at a monthly interval. Use the meter that you created in the previous step.

On the Product catalog page, click Create product.
On the Add a product page, do the following:
- For Name, enter the name of your product. For the Alpaca AI example, enter Alpaca AI.
- (Optional) For Description, add a description that appears in Checkout, in the customer portal and in quotes.
- Select Recurring.
- Under Billing period, select More pricing options.
On the Add price page, do the following:
- Under Choose your pricing model, select Usage-based.
- Choose your pricing structure:
  - For the Alpaca AI example, select Per Unit. Under Price, set the Amount to 0.03 USD.
  - Under Meter, select the meter you created and select Alpaca AI Input tokens from the dropdown.
  - For Billing period, select Monthly.
- Under Meter, select the meter you created. For the Alpaca AI example, select Alpaca AI Input tokens from the dropdown.
- Select the appropriate Billing period. For the Alpaca AI example, select Monthly.
- Click Next.
Repeat the previous steps and create a product named “Alpaca AI output usage” with a price of 0.05 USD. Attach it to the Aplaca AI output token meter with the same monthly billing period.

Create a customer

Next, create a customer.

On the Customers page, click Add customer.
On the Create customer page, do the following:
- For Name, enter the name of your customer. For the Alpaca AI example, enter Jenny Rosen.
- (Optional) Add an email address and description for your customer.
- Click Add customer.

Grant billing credits to your customer

Use the Stripe Dashboard or API to create a credit grant for your customer.

Billing credits only apply to subscription line items that link to a meter price. The Usage Records API isn’t supported.

On the Customers page, select the customer name.
On the customer page, under Credit grants, click the plus (+) symbol.
On the New credit grant page, do the following:

For Name, enter a name for your credit grant.
For Amount, specify the amount of the credit grant. For the Alpaca AI example, enter 10.
(Optional) Under Effective date, specify a date for when to grant the credit.
(Optional) Under Expiry date, specify the date, if any, when the credits expire.
(Optional) Under Priority, specify the priority for this credit grant.
(Optional) Under Eligibility, specify a list of usage-based prices that this credit grant applies to.
Click Create grant.

Create a subscription

Subscriptions allow you to charge recurring amounts by associating a customer with a specific price.

Use the Stripe Dashboard or API to create a subscription that includes your customer, product, and usage-based price.

For the Alpaca AI example, you create a subscription for both the Alpaca AI Input Token and Alpaca AI Output Token products, billed monthly to Jenny Rosen.

Note

You can associate a single metered price with one or more subscriptions.

When you create a billing_mode=flexible subscription, Stripe excludes metered line items from the first invoice since no prior usage exists to bill. Stripe creates an invoice only if the subscription is backdated with previously accrued usage or if pending invoice items exist. When you create a billing_mode=classic subscription, Stripe generates a zero monetary value invoice line item for each metered subscription item.

On the Subscriptions page, click Create test subscription.
On the Create a test subscription page, do the following:
- Under Customer, select the name of your customer. For the Alpaca AI example, select John Doe.
- Under Product, select your prices. For the Alpaca AI example, select the price under Alpaca AI Input Usage and Alpaca AI Output Usage.
- (Optional) Modify the subscription details and settings as needed.
- Click Create test subscription.

Send a test meter event

Use Meter Events to record customer usage for your meter. At the end of the billing period, Stripe bills the reported usage.

You can test your usage-based billing by sending a meter event through the Stripe Dashboard or API. When using the API, specify the customer ID and value for the payload.

After you send meter events, you can view usage details for your meter on the Meters page in the Dashboard.

On the Meters page, select the meter name. For the Alpaca AI example, select Alpaca AI Input tokens.
On the meter page, click Add usage > Manually input usage.
On the Add usage page, do the following:
- Select your customer from the Customer dropdown.
- For Value, enter a sample value. For the Alpaca AI example, enter 3000.
- Click Submit.

Create a preview invoice

Create a preview invoice to see a preview of a customer’s invoice that includes details such as the meter price and usage quantity.

On the Subscriptions page, select a subscription. For the Alpaca AI example, select the subscription for Jenny Rosen.
On the subscription details page, scroll down to the Upcoming invoice section. The preview invoice shows the subscription amount to bill the customer on the specified date.
Click View full invoice to see complete details for the upcoming invoice, including:
- Customer
- Billing method
- Creation date
- Connected subscription
- Subscription details (usage quantity and meter price)
- Amount due
Because Stripe processes meter events asynchronously, upcoming invoices might not immediately reflect recently received meter events.

Apply billing credits to invoices

After the invoice finalizes, Stripe automatically applies all applicable billing credits. The available balance on the credit grant updates based on the amount of billing credits applied to the invoice.

You can find the amount of billing credits applied to an invoice in the Stripe Dashboard.

On the Customers page, select the customer name.
On the customer page, under Invoices, select an invoice.
On the invoice page, under Subtotal, find the line for Credit grant applied.

Retrieve the available billing credit balance

Use the Stripe Dashboard or API to see the available billing credit balance for a customer. When using the API, retrieve the Credit Balance Summary endpoint.

On the Customers page, select the customer name.
On the customer page, under Credit grants, find the list of credit grants that can apply to invoices. You can see the credit grant’s available_balance in the Available column.

List transactions for a credit grant

Use the Stripe Dashboard or API to see the transactions for a specific credit grant or customer. When using the API, call the Credit Balance Transaction endpoint.

On the Customers page, select the customer name.
On the customer page, under Credit grants, select a credit grant.
View details for the credit balance transactions.

OptionalFund the credit grant

Use the Stripe Dashboard or API to create a one-off invoice to collect payment from a customer. When using the API, listen for the invoice.paid webhook and grant billing credits to your customer.

On the Customers page, select the customer name.
On the customer page, click Create invoice.
Follow the instructions to create an invoice.

OptionalRetrieve usage for a custom time period

Use the Meter Event Summary to retrieve total usage for a custom time period. The meter event summary returns a customer’s aggregated usage for a period, based on the aggregation formula defined by the meter.

In the Alpaca AI example, the meter event summary returns the sum of tokens for a specific customer, meter, and time window.

Because Stripe processes meter events asynchronously, meter event summaries might not immediately reflect recently received meter events.