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

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.