Stripe API: Subscription status explained—incomplete, past_due, unpaid…

Subscriptions are complicated. Let’s take a look at the “status” field on Stripe Subscriptions.

The documentation for the Subscription.status enum starts with:

Possible values are incomplete, incomplete_expired, trialing, active, past_due, canceled, or unpaid. However, it’s easier to understand if you split things up into “trialing”, “payment needed”, “active”, “inactive”.

This ordering of the enum values may appear a bit haphazard and you may be wondering, “what’s the difference between incomplete and past_due and unpaid?”, but despite limitations of language, this ordering follows a sound logic for the life-cycle of subscriptions:

1. incomplete - this is for the very first payment of a subscription. Depending on the payment_behavior set for your subscription and if the payment fails or requires additional steps (like 3-D Secure cards), then a subscription will have this status.

2. incomplete_expired - if the subscription is in incomplete for 23 hours, then the customer is not billed and the subscription is effectively canceled and goes to this status.

3. trialing - if the subscription has a trial, it will start with this status until the end of the trial (there is also a non-payment invoice created for the trial).

4. active - the subscription is in good standing.

5. past_due - the most recent invoice (other than the very first, subscription creation invoice) failed or hasn’t been attempted. You can manage your failed payment retries and rules in the Stripe Billing dashboard.

6. canceled - the subscription has been canceled. You’ll encounter an error if you try to update it. Your retry rules can be set up to move failed retries into this status.

7. unpaid - this is an alternative to canceled and leaves invoices open, but doesn’t attempt to pay them until a new payment method is added.

You can read more from Stripe’s subscriptions overview. Do you find these alternate descriptions helpful or are there any inaccuracies?