Managing Subscriptions

Subscription status

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.

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. No new bills will be generated while paused.
`past_due`	The subscription has been marked as past due via the API.
`unpaid`	The subscription has been marked as unpaid via the API.
`cancelled`	The subscription has ended. This occurs automatically when the cycle limit is reached, or manually via the API.

Activating an incomplete subscription

If a subscription was created without payment methods, it will have a status of incomplete. To activate it, submit a POST request to the /subscriptions/{subscription_id}/activate endpoint with the required payment methods.

For more information, please refer to our activate subscription API reference.

/subscriptions/{subscription_id}/activate request:

{
  "payment_methods": [
    {
      "type": "card",
      "payment_method_id": "00cfdbdc-5e81-4ce2-adc1-14920120618f",
      "is_primary": true
    }
  ]
}

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.