How to check a Stripe subscription’s status

Read it from your own store, and let webhooks keep that store correct. Asking the Stripe API every time you need the answer is where almost everyone starts, and it is the thing you eventually have to undo, because it puts a rate-limited network call inside the request your user is waiting on and ties your availability to someone else’s.

The second half of the problem is harder than the first and gets much less attention: once you have the status, deciding what each value means is a product decision that Stripe’s reference deliberately will not make for you. Eight values, and the interesting ones are not the two you expect.

Webhook-driven state, or polling

Polling the Stripe API compared with keeping webhook-driven state, across six dimensions
 Polling the APIWebhook-driven state
Where the answer comes fromA live API call to Stripe at the moment you need it.Your own store, which a webhook updated when the change happened.
Latency on the hot pathA network round trip on every check, inside the request the user is waiting on.A local read. Usually a single indexed row.
When Stripe has an incidentYour app degrades or fails, including for users who are not buying anything.Your app is unaffected. New changes queue up and arrive when Stripe recovers.
Rate limitsShared across your whole account, so a traffic spike can throttle real checkouts.Not involved.
StalenessNone. This is its one real advantage.Seconds, usually. A delivery can be retried, which is why the receiver has to be idempotent.
What it costs to buildAlmost nothing, which is why it is where everyone starts.A verified endpoint, a replay guard and a table. Described below.

The reason this is not close is that the two costs scale against different things. Polling costs you a call per access check, which grows with your traffic. Webhooks cost you a write per billing change, which grows with your billing events, and billing events are rare: a subscriber generates a handful a year while generating thousands of access checks. Keep one direct API read for the moments immediately after checkout, where you cannot afford to wait for the event to arrive.

The status lifecycle, and what each value should grant

This is Stripe’s own set for a Subscription object. The middle column is what the value means and comes from Stripe. The right column is a judgement call that Stripe’s reference will not make for you, which is exactly why this question gets asked.

Each Stripe subscription status, what it means, and whether it should grant access
StatusWhat it meansGrant access?
incompleteThe first payment has not succeeded yet. Stripe keeps the subscription in this state for 23 hours while the customer finishes authentication, then gives up.No. Nothing has been paid.
incomplete_expiredThat 23 hours ran out without a successful first payment. This state is final.No, and it never will. Treat it as a checkout that was abandoned.
trialingInside a trial period. There may be no payment method attached at all, and no money has moved.Yes. The whole point of a trial is access before payment, and treating it as unpaid is the single most common gating bug.
activePaid and current. The ordinary state.Yes.
past_dueA renewal payment failed and Stripe is retrying on your configured schedule. The subscription has not ended.Your decision, and it is a real one. Cutting access instantly punishes an expired card. A short grace period with a prompt to update the card recovers most of them.
canceledEnded. Either the customer cancelled and the period ran out, or the retries were exhausted.No.
unpaidRetries were exhausted and your settings told Stripe to leave the subscription open and unpaid rather than cancel it.No, but the record is still there, so a reactivation is possible.
pausedA trial ended with no payment method and your settings pause rather than cancel. Not the same thing as a customer-requested pause.No.

Two of these account for most of the bugs. trialing is read as unpaid, so trials do not work and nobody notices until a trial user complains. And past_due gets decided implicitly, by whichever branch of whichever gate happened to be written first, so the same customer is locked out of one screen and not another.

The state that is not a status

Knowing the eight values is necessary and not sufficient. These four things are not in the status field at all, and each one is a question your app will eventually have to answer.

cancel_at_period_end

A customer who has cancelled is still `active` until the period ends. The status alone will tell you they are fine and the renewal will not happen. If you want to show a "your plan ends on" banner, or run a win-back, this boolean is what you read, not the status.

current_period_end

When the access you granted actually runs out. Needed for anything you want to display, and for deciding whether a `canceled` subscription still has paid time left on it.

The price or product id

Status answers whether they pay. It does not answer which tier they bought, and almost every gate in a real app is a tier comparison rather than a yes or no. You have to map the price id back to your own plan yourself.

One-time purchases

A lifetime deal or a single licence is not a Subscription object at all, so it has no status to read. If you sell both, the "is this user paid" question spans two different Stripe objects and your own state has to reconcile them.

The pattern, in six rules

  1. Keep your own row per customer, written by the webhook. That row is what your app reads, every time.
  2. Verify the webhook signature against the raw request body, before anything parses it.
  3. Make the handler idempotent by claiming the Stripe event id in a table with a unique constraint, because Stripe retries and operators resend by hand.
  4. Subscribe to the events that take access away, not only the ones that grant it. customer.subscription.deleted and charge.refunded are the ones people forget.
  5. Store the derived answer, not just the raw status, so every part of your app agrees on what past_due means.
  6. Reconcile on a schedule. A webhook you failed to process once is a user in the wrong state forever unless something checks.

The last one is the one that gets skipped. Webhook delivery is reliable and not perfect, and the failure is silent on both sides: Stripe recorded a delivery attempt, your logs recorded an error nobody read, and a customer is paying for something they cannot use. A nightly job that compares your rows against Stripe’s is unglamorous and catches it.

If you have not built the receiving side yet, that is its own subject: what adding Stripe payments without a backend actually requires.

Questions

How do I check if a user has an active Stripe subscription?

Read it from your own database, not from Stripe, and keep that record current with webhooks. Calling the Stripe API on every check puts a rate-limited network round trip inside the request your user is waiting on, and makes your app fail whenever Stripe does. The webhook writes the state when it changes; your app reads a local row when it needs it.

Should I poll the Stripe API or use webhooks?

Webhooks for keeping state, with a scheduled reconciliation as the backstop. Polling is a reasonable way to start and an unreasonable way to stay, because its cost grows with your traffic rather than with the number of billing changes, and billing changes are rare. Keep one API read for the moment immediately after checkout, where you genuinely cannot wait for the event.

What are the Stripe subscription statuses?

incomplete, incomplete_expired, trialing, active, past_due, canceled, unpaid and paused. Stripe documents what each one means but deliberately does not say which should grant access, because that is your product decision. In practice trialing and active grant it, incomplete, incomplete_expired, canceled, unpaid and paused do not, and past_due is the one you have to decide deliberately.

Does trialing count as an active subscription?

For access, yes. A trialing subscription may have no payment method attached and has certainly not paid, but refusing access during a trial defeats the trial. Treating trialing as unpaid is the most common subscription gating bug.

What should I do when a subscription is past_due?

Decide it on purpose rather than by accident. past_due means a renewal failed and Stripe is still retrying, usually over days. Cutting access immediately punishes an expired card and loses customers who would have paid; a short grace period with a visible prompt to update the card recovers a good share of them. What matters is that the rule is written down once and applied everywhere.

Why is a cancelled subscription still showing as active?

Because cancelling at period end does not change the status. The subscription stays active until the period actually ends, and the thing that changed is cancel_at_period_end, which is a separate boolean. If you only read status you will see a healthy subscription and miss that it will not renew.

How do I know which plan a subscriber is on?

The status does not tell you; the price id on the subscription does, and you have to map it back to your own plan definitions. This matters more than it sounds, because most real gates are tier comparisons rather than a paid-or-not check, and a price id that is no longer in your plan list will otherwise silently demote a paying customer.

How does SparkPay expose subscription status?

As one HTTP GET returning the stored subscription row plus a resolved access block, so the calling app does not reimplement the status rules. Its stored status field carries active, trialing, past_due and canceled; the other Stripe states are transient or terminal and do not become a stored row. The endpoint is unauthenticated by design, so that a client with no backend can call it, and is rate limited because an email lookup is an enumeration surface.

How SparkPay does the status read

For the reader who would rather not build the receiving half: SparkPay keeps the webhook-driven row and exposes it as one HTTP GET, taking an email and an app id. The response carries the stored subscription fields, including status, current_period_end and cancel_at_period_end, and alongside them a resolved access block, so the calling app is not reimplementing the rules in this page for itself. A past_due subscriber keeps their resolved tier while being flagged as not currently paid, which is what lets the grace-period decision above be made once rather than per gate.

Two honest limits. Its stored status field carries active, trialing, past_due and canceled. The remaining Stripe states are either transient before a subscription exists or terminal, and do not become a stored row, so this is not a mirror of Stripe’s full set. The endpoint is also deliberately unauthenticated, because its purpose is to be callable from a client that has no backend, which makes it an email-enumeration surface and is why it is rate limited. Neither is a problem, but both are the kind of thing worth knowing before you depend on it rather than after.