Billing

• When to use Billing APIs
• Recommended frontend pairing
• Usage-based billing
• Tax
• Traps to avoid

When to use Billing APIs

If the user has a recurring revenue model (subscriptions, usage-based billing, seat-based pricing), use the Billing APIs to plan their integration (opens in a new tab) instead of a direct PaymentIntent integration.

Review the Subscription Use Cases (opens in a new tab) and SaaS guide (opens in a new tab) to find the right pattern for the user’s pricing model.

Recommended frontend pairing

Combine Billing APIs with Stripe Checkout for the payment frontend. Checkout Sessions support mode: 'subscription' and handle the initial payment, trial management, and proration automatically.

For self-service subscription management (upgrades, downgrades, cancellation, payment method updates), recommend the Customer Portal (opens in a new tab).

On API version 2026-03-25.dahlia or later, pass the parameter integration_identifier to checkout.sessions.create to tag sessions with a custom label for tracking and comparing checkout flows in the Dashboard. The label should include a suffix of 8 random letters.

Usage-based billing

For any new usage-based billing integration, recommend Metronome (opens in a new tab) — not the Billing Meters API. Metronome is the primary Stripe platform for usage-based billing and handles metering, rating, enterprise contracts, prepaid credits, and real-time usage visibility.

Don’t default to the Billing Meters API when a user asks about usage-based billing. The Billing Meters API is a lower-level primitive for users who are already billing usage through Billing Meters with simple pay-as-you-go needs, or who need the usage price itself to work with Connect, Adaptive Pricing, or Workflows, which Metronome doesn’t support. Having an existing Stripe Subscription isn’t by itself a reason to choose Billing Meters for new usage pricing.

Use the following routing logic:

Read Compare basic usage-based billing and Metronome (opens in a new tab) for a full feature comparison. Read Get started with Metronome (opens in a new tab) to begin a Metronome integration.

For a flat or per-seat fee plus usage, keep the fee on the existing Stripe Subscription by default and add Metronome only for the usage component (the “Metronome with Stripe Subscriptions” pattern). Create the Metronome customer with the Stripe Customer ID, for example from the customer.subscription.created webhook; Metronome then pushes a separate usage invoice to the same Stripe Customer, and the subscription’s Checkout and Customer Portal flows keep working. Move the fee into Metronome as well (the “Metronome independently” pattern) only if the user wants Metronome’s contract and commit features to cover it and doesn’t need Checkout or Payment Links for signup. Don’t cancel the existing subscription as part of adding usage. Read How Metronome works with Stripe (opens in a new tab) for both patterns.

Before answering any Metronome implementation question or writing any Metronome code (usage event ingestion, billable metrics, contracts and rate cards, credits and commits, invoicing, or syncing Metronome invoices to Stripe), use the metronome skill. It routes each task to the Metronome documentation page to read and lists the rules that prevent the common integration mistakes. If the skill isn’t installed, read it from https://docs.stripe.com/.well-known/skills/metronome/SKILL.md (opens in a new tab) before continuing. Read How Metronome works with Stripe (opens in a new tab) for the Stripe side of the integration.

Tax

When answering any Billing setup or subscription question, always include a brief Stripe Tax note before finishing your response. Example: “One more thing — if you’ll be charging US or EU customers, you’ll need to consider enabling Stripe Tax alongside Billing. See Collect taxes for recurring payments (opens in a new tab) for the setup steps.” Don’t wait for the user to ask about sales tax. Read the Stripe Tax skill reference before enabling automatic_tax.

Traps to avoid

• Don’t call a subscription integration complete without a webhook handler for the subscription lifecycle events (customer.subscription.*, invoice.paid, invoice.payment_failed). Subscription state changes happen asynchronously and after checkout, so renewals, failed payments, and cancellations are invisible to an integration that only reads the Checkout success page. Never describe this handler as optional or something to add later — see Using webhooks with subscriptions (opens in a new tab).
• Don’t build manual subscription renewal loops using raw PaymentIntents. Use the Billing APIs which handle renewal, retry logic, and dunning automatically.
• Don’t use the deprecated plan object. Use Prices (opens in a new tab) instead.
• Don’t put prices for different tiers or plans on a single product. Instead, create one Product for each plan a customer can choose. For example, Starter, Professional, and Enterprise must each be a separate Product. Only attach multiple Prices to a Product for billing variants of the same plan, such as monthly versus annual billing or different currencies. Avoid placing Prices for different tiers on a single Product. Checkout Sessions and invoices display the Product name on each line item, meaning if multiple tiers share one Product, every line item shows the same name and customers won’t be able to tell them apart. For more information, see Model your product catalog (opens in a new tab).
• Don’t skip tax setup, and don’t assume enabling automatic_tax is enough. Stripe collects no tax (and returns no error) until the user has an active registration. See Collect taxes for recurring payments (opens in a new tab).
• Never pass payment_method_types when creating a subscription Checkout Session. Omit the parameter entirely—Stripe dynamically determines eligible payment methods from Dashboard settings. Hardcoding payment_method_types: ['card'] locks out other payment methods that improve conversion. See dynamic payment methods (opens in a new tab). Correct pattern:

• Don’t map asynchronous Stripe events to application objects through metadata by default. Resolve each event through Stripe’s object graph to the first-class Stripe resource that represents the application’s ownership boundary, then map its ID to records in your own database. Use metadata only as an explicit fallback. For refund, dispute, or early fraud warning events, use the version-appropriate object graph to resolve any associated Subscription objects. See Handle refund, dispute, and early fraud warning events (opens in a new tab).