Skip to main content

Subscription flow

This page describes the end-to-end flow of a subscription, from creating the product the customer is buying to the first renewal and beyond. Each step links to the page that covers it in depth.

The 11 steps​

1. Create the product​

The product is what the customer is buying — see Product CRUD.

2. Create the plan​

The plan defines pricing and billing cadence (recurringInterval). For a recurring plan, the interval is set; for a one-time plan, it is omitted. See Plan CRUD and Products and plans.

3. Create the customer​

The customer is the entity being billed — see Customers.

4. Tokenize and attach a payment instrument​

Card data is tokenized client-side (typically by FramePay) and the token is exchanged for a paymentInstrumentId attached to the customer. The instrument starts as inactive — see Payment instrument lifecycle and Create customer with payment instrument.

5. Create the subscription​

POST /subscriptions with the customer, payment instrument, plan, and the required field isTrialOnly. With an inactive instrument, the response returns status: "pending" and a recentInvoicePaymentFormUrl — the customer is redirected to the hosted payment form to complete the first payment. See Create a subscription and Required fields.

6. Trial handling​

If the plan has a trial, the subscription enters the trial period instead of being billed immediately. The trial ends on the configured end date and the subscription moves to its first paid renewal. See Trial.

7. First renewal — auto-charge on active instrument​

After the first hosted-form payment (or, for a trial subscription, after the trial ends), the payment instrument is active. From then on, PaymentsAI auto-charges renewals on schedule against the active instrument. No redirect, no customer interaction. See Billing cycles.

8. Payment failure and dunning​

When a renewal charge fails, the subscription moves to unpaid and PaymentsAI retries the payment according to the plan's retry configuration. If retries succeed, the subscription returns to active. If they exhaust, the subscription moves to churned. See Dunning and retries.

9. Pause and resume​

The merchant or customer can pause an active subscription. Paused subscriptions do not renew. See Subscription pauses.

10. Plan change — upgrade or downgrade​

A subscription's plan can be changed via POST /subscriptions/{id}/items. The retainRenewalTime and proRataCredit flags control timing and proration. See Upgrade and downgrade and Proration.

11. Cancel and reactivate​

Subscriptions can be canceled immediately or scheduled to cancel on a future date via cancelAt. A canceled subscription can be reactivated; the API response confirms whether reactivation succeeded. See Subscription cancellations and Subscription reactivation.

State-machine rules​

A few hard rules apply to subscription state transitions:

  • Only an active subscription can be paused.
  • Deleting a pause resumes the subscription to active.
  • A paused subscription cannot be canceled directly — resume it first.
  • Only an active subscription can be canceled.
  • A canceled subscription can be reactivated (while still inside the cancellation window).

For the full status list and the diagram, see Subscription statuses.