Stripe: metered billing subscription with a trial period, in the right order

TL;DR

Create the subscription with trial\period\days set (e.g. Do not set both. - During the trial the customer owes nothing, but metered usage still accumulates. A trial is not a pause on metering. - Webhook customer.subscription.trial\will\end fires a few days before the trial ends.

When to use

You are seeing this: Create the metered price: a recurring price with usage-based billing (billing\scheme tiered or per-unit with usage\type metered, or a Billing Meter for the current API). Use this skill when you run into "Stripe: metered billing subscription with a trial period, in the right order".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Stripe: metered billing with a trial, in order

The sequence

Order matters. Do it in this order:

1. Create the customer.
2. Create the metered price: a recurring price with usage-based billing (billing_scheme tiered or per-unit with usage_type metered, or a Billing Meter for the current API).
3. Create the subscription with trial_period_days set (e.g. 14). No payment method is charged during the trial, but the subscription exists and usage can be recorded against it.
4. Report usage as it happens during the trial.
5. At trial end Stripe bills for the recorded usage. Verify the first invoice before considering it done.

Trial facts agents get wrong

• trial_period_days counts from subscription creation. trial_end takes an exact timestamp instead. Do not set both.
• During the trial the customer owes nothing, but metered usage still accumulates. A trial is not a pause on metering.
• Webhook customer.subscription.trial_will_end fires a few days before the trial ends. Listen for it if you notify users.
• Test the whole flow with a test clock: create the clock, attach the customer, advance past the trial, read the invoice.

Current docs note

Stripe's usage-based billing docs now steer new integrations toward Metronome ("use Metronome for most use cases including starting a new integration") unless you maintain an existing Billing Meters integration. Check the current usage-based billing overview before choosing; the sequence above holds either way, but the usage-reporting API differs.

Checklist

• Price is metered/usage-based, not flat, before the subscription references it.
• Trial length is explicit in the subscription create call.
• First invoice after trial end is reviewed in test mode with a test clock.

Subscription creation accepts trialperioddays (days from creation) or trialend (exact timestamp), per the API reference (docs.stripe.com/api/subscriptions/create). Stripe's usage-based billing overview states "use Metronome for most use cases including starting a new integration" unless maintaining an existing Billing Meters integration (docs.stripe.com/billing/subscriptions/usage-based, redirected from the former metered URL). Trial behavior (no charge during trial, usage still recorded, trialwillend event) is documented billing behavior. Test clocks (docs.stripe.com/api/testclocks) compress the trial timeline for verification. Verified against live docs 2026-09-26.