​
1. Create your catalog

Create a product for the plan and a recurring price for its billing interval. Add coupons and tax settings where applicable. Keep the price interval and amount immutable for existing subscribers. Create another price when the plan changes materially and use an explicit plan-change operation.

​
2. Create or find a customer

Use a stable customer record for the account that owns access. Store your internal account ID in metadata.

​
3. Start the subscription

Create a subscription with the customer, price, optional trial, discount, and return URLs. Use an idempotency key so a network retry cannot create a second subscription. For a customer who must complete payment, create the related checkout flow and keep the subscription incomplete or otherwise pending until the first invoice is confirmed. Persist your account ID in metadata and store the subscription and invoice IDs.

​
4. Provision access from events

Grant access after the subscription or first invoice is confirmed. Handle renewal, payment failure, cancellation, pause, resume, and trial-ending events. A browser return is not a billing confirmation.

​
5. Give customers control

Create a customer-portal session so customers can update payment details, review invoices, change plans, pause service, or cancel according to your policy.

​
Trial and cancellation policy

Tell customers when the trial ends, what starts the first charge, and whether cancellation is immediate or at period end. A cancellation request may be retried safely with an idempotency key; reconcile the resulting subscription event before changing access.