Create hybrid pricing plans非公開プレビュー

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.

プライベートプレビュー

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

メーターは、請求期間中のメーターイベントを集計する方法を指定するものです。メーターイベントは、顧客がシステムで実行するすべてのアクション (API リクエストなど) を表します。メーターは料金に関連付けられており、請求内容の基礎になります。

Alpaca AI の例では、メーターイベントは顧客がクエリで使用するトークンの数です。メーターは 1 カ月あたりのトークンの合計です。

Stripe ダッシュボードまたは API を使用して、メーターを設定できます。Stripe CLI で API を使用してメーターを作成するには、Stripe CLI の使用を開始します。

メーターページで、メーターを作成をクリックします。
メーターを作成ページで、以下を実行します。
- メーター名には、表示用および社内用のメーターの名前を入力します。Alpaca AI の例では、「Alpaca AI tokens」と入力します。
- イベント名に、使用量を Stripe に報告するときにメーターイベントに表示する名前を入力します。Alpaca AI の例では、「alpaca_ai_tokens」と入力します。
- ドロップダウンで適切な 集計方法 を設定します。
  - Alpaca AI の例では、合計を選択します。これにより、報告された「値の合計」 (この例では顧客が使用するトークンの数)が出され、請求する使用量が決定されます。
  - 報告されたイベントの「数」に基づいて請求する件数を選択します。
  - 最後を選択すると、報告された「last value」に基づいて請求できます。
  - プレビューペインを使用して、使用状況イベントの例を設定し、集計方法を確認します。
- メーターを作成をクリックします。

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.

注

Create hybrid pricing plans非公開プレビュー

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

プライベートプレビュー

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

オプションCollect taxes

注

Create hybrid pricing plans非公開プレビュー

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

プライベートプレビュー

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

オプションCollect taxes