Managing Subscriptions

Subscription statuses

The initial status of a subscription depends on whether payment methods are provided at creation:

• With payment methods — the subscription is created as active and billing begins immediately. If a trial_end was supplied, it is created as trialing instead and no payment is taken until the trial ends.
• Without payment methods — the subscription is created as incomplete and must be activated before billing can begin.

Activating an incomplete subscription

If a subscription was created without payment methods, it will have a status of incomplete. To activate the subscription, you have two options:

1. Submit a POST request to the /subscriptions/{subscription_id}/activate endpoint with the required payment methods.
2. When you include a subscription_id in a Components /payment-sessions request, the session inherits configuration from the subscription to capture the customer's card and/or take an initial payment, and then automatically activates the subscription on completion — all in one step.

For more information, refer to our activate subscription API reference. and Components integration guide.

/subscriptions/{subscription_id}/activate request:

{
  "payment_methods": [
    {
      "type": "card",
      "payment_method_id": "00cfdbdc-5e81-4ce2-adc1-14920120618f",
      "is_primary": true,
      "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}

The transaction_id is optional. If provided, it links a previous payment transaction to the subscription for prepaid billing flows.

Once activated, the subscription transitions to active (or trialing when a trial_end was set) and the first bill is created automatically.

Updating subscription status

You can transition an active subscription to the following statuses via the API:

• Cancel — POST /subscriptions/{subscription_id}/cancel — permanently ends the subscription. cancelled is a terminal status: once cancelled, a subscription cannot transition to any other status.
  • Immediately (default) — the subscription transitions to cancelled straight away and any outstanding draft bills are voided.
  • At period end — pass the ?at_period_end=true query parameter to schedule the cancellation instead. The subscription keeps its current status and cancel_at_period_end is returned as true on the subscription. When the next bill becomes due, that bill is voided and the subscription is cancelled automatically.
• Pause — POST /subscriptions/{subscription_id}/pause — temporarily halts billing. While paused, no payment is taken: when a bill becomes due it is voided and a new draft bill is created for the next cycle, so billing resumes automatically once the subscription is set to active again. Subscriptions in trialing or incomplete status cannot be paused.
• Past due — POST /subscriptions/{subscription_id}/past_due — marks the subscription as past due.