Managing Subscriptions

Subscription statuses

Status	Description
`incomplete`	The subscription has been created but has no payment methods. It must be activated before billing can begin.
`active`	The subscription is active and bills are being generated and processed.
`paused`	The subscription has been paused via the API, or the Hub. No new bills will be generated while paused. Existing `draft` or `open` bills will continue to have payment taken against them unless they are marked as `void`.
`past_due`	The subscription has been marked as past due via the API. The subscription continues to operate as if `active`, therefore bills are generated and processed.
`unpaid`	The subscription has been marked as unpaid via the API. The subscription continues to operate as if `active`, therefore bills are generated and processed.
`cancelled`	The subscription has ended. This occurs automatically when the cycle limit is reached, manually via the API, or the Hub.

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.
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:

Submit a POST request to the /subscriptions/{subscription_id}/activate endpoint with the required payment methods.
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 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.
Pause — POST /subscriptions/{subscription_id}/pause — temporarily halts billing. Any existing bills will continue to have payment attempted against.
Past due — POST /subscriptions/{subscription_id}/past_due — marks the subscription as past due.
Unpaid — POST /subscriptions/{subscription_id}/unpaid — marks the subscription as unpaid.

📘
Note
A subscription is also automatically cancelled when its billing cycle limit is reached. See Bills for more details on the billing lifecycle.