Create hybrid pricing plansVersion bêta privée

Bill your customers based on usage, recurring charges and credit grants, or one time fees.

You can group different pricing components into a single pricing plan. For example, you can create a pricing plan that includes rate cards for usage-based billing, license fees for recurring charges, and service actions for recurring credit grant allocations. When a customer subscribes to a pricing plan, all the recurring components are automatically enrolled and billed according to the cadence you configure. Supported pricing models include pay as you go and credit burndown.

Version bêta privée

Pricing plans are currently in private preview and could change in functionality and integration path before they’re generally available to all Stripe users. Contact us here to request access.

Before you begin

Pricing Plans use /v2 API endpoints. Learn more about the /v2 and /v1 namespaces.

Use sandboxes to test your pricing plans integration. You can’t use test mode with /v2 APIs.

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 tokens a customer uses in a query. The meter is the sum of tokens over a month.

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 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_tokens.”
- Set the approproriate 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.

Create a pricing plan

Use the Stripe Dashboard or API to create a pricing plan that contains all the relevant billing components of your pricing model.

For each pricing plan, you can configure:

Currency
Include tax in prices: Specify whether to include tax in your price (inclusive) or to add it to the invoice subtotal (exclusive). Learn more about inclusive and exclusive taxes for billing.
Metadata: Optionally add your own metadata to the pricing plan.

After you set the currency, and tax parameters, define the relevant components of your plan. Which components you include depends on your pricing model. For this example, create a rate card for usage-based billing.

For usage-based billing, you also need to create a meter (or use an existing one) to record usage events.

When you create a pricing plan, provide a display name, currency, and specify the tax behavior (learn more about tax behavior and rate cards).

After you submit the pricing plan request, Stripe returns the active Pricing Plan object. You can’t subscribe new customers to an inactive pricing plan.

pricing plan response example
{
  "id": "bpp_test_61SjPwyNGx88hyuOg16SjPfE4ZSQFjWjdqlzQfWMCH1E",
  "object": "v2.billing.pricing_plan",
  "active": true,
  "created": "2025-06-14T21:52:04.000Z",
  "currency": "usd",
  "description": null,
  "display_name": "Pro Pricing Plan",
  "latest_version": "bppv_test_123",
  "live_version": "bppv_test_123",
  "lookup_key": null,
  "metadata": {},
  "tax_behavior": "exclusive"
}

You can add an existing component to your pricing plan by referencing its ID and version.

Add a rate card

To attach a rate card to your pricing plan, first create a rate card and provide a display name, currency, service interval, and tax behavior.

After you create the rate card, you can add it to the pricing plan:

Add a license fee

License fees are fixed recurring charges, which which you can use to charge up-front fees.

First, create a license item:

Then, create a license fee:

Finally, attach the license fee to a pricing plan:

Add a service action

You can add new components, including recurring credit grants, to your pricing plan. Use recurring credit grants if you use a credit burndown pricing model. Service actions let you offer recurring credits to customers, which can offset charges for specific billable items, such as usage-based fees.

When you create a service action, you configure:

Amount
Billing frequency
Applicable billable items

To create a monthly credit grant of 10 USD that applies a to a specific billable item and expires at the end of the service interval:

Attach the service action to your pricing plan:

Activate the pricing plan

After you’ve added the relevant components for your pricing model, activate that version of the pricing plan. After the plan is activated, you can subscribe customers to it.

Before you create a subscription, you need to create a Customer object and provide billing information. You can do so in the Dashboard, with the API, or by using Stripe Checkout.

Checkout Session limitations during private preview

Use the Checkout Sessions API to create a checkout page for your customers. When a customer clicks Subscribe, it creates a Customer object and a pricing plan subscription. If you have multiple items in checkout_items, a pricing plan subscription is created for each item.

Here’s an example of what a complete pricing plan looks like with Checkout.

A pricing plan displayed in Stripe Checkout

To create a Checkout Session with pricing plans, include the checkout_items hash containing an object that has its type set to pricing_plan_subscription_item and includes a pricing_plan_subscription_item configuration. When you use checkout_items instead of line_items, you don’t need to specify the mode.

When you create the Checkout Session, redirect the customer to the Session’s url. Learn more about how you can configure Checkout’s redirect behavior.

The page displays your pricing plan’s details and collects the customer’s payment information. After the customer completes the session, the pricing plan subscription is created and the customer is redirected to the URL you specified for success_url. Learn more about customizing redirect behavior with Checkout.

Record customer usage

After you subscribe a customer to a pricing plan consisting of a rate card, record their usage of your service by sending meter events to a meter.

Go to the Pricing plan subscriptions tab.
Click the subscription you want to record usage for.
Select View to see the underlying pricing plan components, and navigate to the rate card you want to add usage for.
Click the overflow menu () in the row of the item you want to record usage for, then click View meter details.
In the meter details page, click + Add usage then select Manually input usage.
In the Add usage dialog:
- Select a customer.
- Enter a Value for the usage.
- Select a date for the Timestamp.
Click Submit.

Create a preview invoice

Create a preview invoice to see a preview of a customer’s invoice. The preview includes the relevant line items from the various pricing plan components.

Go to the Pricing plan subscriptions tab.
Click the subscription you want to preview an invoice for.
Scroll down to the Upcoming invoice section. The preview invoice shows the subscription amount to bill the customer on the specified date, and reflects the corresponding metered items, license items, and credits.
Click View full invoice to see complete details for the upcoming invoice, including:
- Customer
- Billing method
- Creation date
- Connected subscription
- Subscription details (metered items, license items, and credits)
- Amount due
Because Stripe processes meter events asynchronously, upcoming invoices might not immediately reflect recently received meter events.

Monitor servicing events

Pricing plan subscriptions send event notifications whenever the servicing and collection states change. Learn more about how the service interval works.

Listen for these events and use them to construct your business logic:



`v2.billing.pricing_plan_subscription.servicing_activated`	The user pays the subscription which activates the service.
`v2.billing.pricing_plan_subscription.servicing_paused`	The user pauses the subscription.
`v2.billing.pricing_plan_subscription.servicing_canceled`	The user cancels the service.
`v2.billing.pricing_plan_subscription.collection_current`	The collection of the subscription is ongoing.
`v2.billing.pricing_plan_subscription.collection_awaiting_customer_action`	The collection is waiting for the customer to do something.
`v2.billing.pricing_plan_subscription.collection_paused`	The collection is paused.
`v2.billing.rate_card_subscription.collection_past_due`	The collection is past due.
`v2.billing.rate_card_subscription.collection_unpaid`	The collection is considered unpaid.

To handle these v2 Events, configure an Event Destination and point it at your webhook endpoint. You can either:

Create the Event Destination from Workbench.
Create the Event Destination through the Stripe API.

After you’ve created a destination, you can set up your webhook endpoint to handle these events:

server.rb
require 'stripe'

post '/v2_webhook_endpoint' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']
  event = nil

  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    status 400
    return
  end

  client = Stripe::StripeClient("sk_test_BQokikJOvBiI2HlWgH4olfQ2"
)

  case event.type
  when 'v2.billing.pricing_plan_subscription.servicing_activated'
    # The customer clicked Pay on Stripe Checkout, which activates the service.
    subscription_id = event.related_object.id
    subscription = client.v2.billing.pricing_plan_subscriptions
      .retrieve(subscription_id)

    # Look up your user in the database using the metadata passed into
    # Checkout Session create
    user_id = subscription.metadata["my_user_id"]
    user = User.find_by_id(user_id)

    # Fill in your logic here:
    mark_subscription_active(user, subscription)
  when 'v2.billing.pricing_plan_subscription.servicing_paused'
    # The customer paused the subscription.
    subscription_id = event.related_object.id
    subscription = client.v2.billing.pricing_plan_subscriptions
      .retrieve(subscription_id)

    # Look up your user in the database using the metadata passed into
    # Checkout Session create
    user_id = subscription.metadata["my_user_id"]
    user = User.find_by_id(user_id)

    # Fill in your logic here:
    mark_subscription_paused(user, subscription)
  when 'v2.billing.pricing_plan_subscription.servicing_canceled'
    # The customer canceled the subscription.
    subscription_id = event.related_object.id
    subscription = client.v2.billing.pricing_plan_subscriptions
      .retrieve(subscription_id)

    # Look up your user in the database using the metadata passed into
    # Checkout Session create
    user_id = subscription.metadata["my_user_id"]
    user = User.find_by_id(user_id)

    # Fill in your logic here:
    mark_subscription_canceled(user, subscription)
  end

  status 200
end

Test the integration

To test your integration:

Create a sandbox.
Create a test pricing plan and at least one underlying pricing component in your sandbox.
Use test cards to simulate successful and failed payments.
Create test meter events to simulate usage.
Use test clocks to simulate billing.

Don't create test clocks in the past

When you create a test clock for a pricing plan subscription, only create clocks in the future. If create a clock in the past, invoice amounts won’t be correct.

First, configure your collection settings. The collection_method parameter defines whether to send an invoice to the payer (send_invoice) or attempt to charge the payer immediately (charge_automatically). If you set it to charge_automatically, the pricing plan subscription is created after the first successful payment.

Create a test clock with a UNIX timestamp:

Make a note of the test clock’s ID. Next, create a test customer with the clock:

Create a billing cadence to define when to bill the customer. Save the ID.

Create a pricing plan subscription for the test customer.

Create a billing intent to track the status of the pricing plan subcription. First, you create a draft billing intent. Save the ID of the intent.

Next, reserve the billing intent:

Next, commit the billing intent to activate the pricing plan subscription and bill the customer according to the plan and cadence. (If you configured collection settings to charge_automatically, you must have a successful PaymentIntent to commit the Intent.)

Pay the invoice generated by the subscription. After the invoice is paid, you can simulate usage and advance the clock, which triggers the next month’s billing. If you use Checkout, you can open the returned Checkout Session’s url in your browser and complete payment with a test card.

Record some test usage:

Advance the test clock’s frozen time forward by a month. In this example, the test clock currently has a timestamp of 1577836800. To add a month, add 30 * 24 * 60 * 60, or 2592000 seconds. The new timestamp a month from now is 1580428800.

Remarque

Create hybrid pricing plansVersion bêta privée

Bill your customers based on usage, recurring charges and credit grants, or one time fees.

Version bêta privée

Before you begin

Create a meter

Create a pricing plan

Add a rate card

Add a license fee

Add a service action

Activate the pricing plan

Checkout Session limitations during private preview

Record customer usage

Create a preview invoice

Monitor servicing events

Test the integration

Don't create test clocks in the past

FacultatifCollect taxes

Remarque

Create hybrid pricing plansVersion bêta privée

Bill your customers based on usage, recurring charges and credit grants, or one time fees.

Version bêta privée

Before you begin

Create a meter

Create a pricing plan

Add a rate card

Add a license fee

Add a service action

Activate the pricing plan

Subscribe your customer to a pricing plan

Checkout Session limitations during private preview

Record customer usage

Create a preview invoice

Monitor servicing events

Test the integration

Don't create test clocks in the past

FacultatifCollect taxes