Subscription states
Every state a Metric Vault subscription can be in, whether it still gives you access, and how the platform keeps your plan in sync with it.
Last updated 2026-08-06
Summary#
A Metric Vault subscription is held in Stripe, and its status there is what decides the plan on your account. Three statuses give you full paid access: active, trialing and past_due. Everything else drops the account to Free. This page lists every state, what it means for access, and how quickly a change reaches the product.
Overview#
There are two separate things, and keeping them apart explains almost every question support receives about plans:
- Your subscription status lives with the payment provider. It changes when you subscribe, when a trial ends, when a card fails, when you cancel.
- Your plan on your Metric Vault account is a record on our side. It is what the credit quota, the seat cap and the feature gates read.
The platform keeps the second in step with the first, in two ways. Payment events are delivered to Metric Vault as they happen, so a successful checkout or a cancellation normally applies within seconds. Independently, a reconciliation job runs on a regular cycle, re-reads the live subscription list, and corrects anything the event stream missed. That belt-and-braces design is why a plan that looks wrong almost always fixes itself within about fifteen minutes.
Status reference#
| Status | What it means | Paid access | Typical cause |
|---|---|---|---|
active | The subscription is paid and current | Yes, full plan | Normal state |
trialing | Inside the 14-day free trial | Yes, full plan quota | A new subscription with a trial |
past_due | A charge failed and the provider is retrying | Yes, deliberately | Expired or declined card |
canceled | The subscription has ended | No, drops to Free | You cancelled, or retries were exhausted |
unpaid | Retries were exhausted and the invoice is unpaid | No, drops to Free | Long-running payment failure |
incomplete | The first payment was never confirmed | No | Checkout abandoned at the payment step |
incomplete_expired | An incomplete first payment timed out | No | Checkout abandoned and left |
paused | Collection is paused | No | Not used by Metric Vault |
Important: past_due keeps your access. When a card fails, cutting off a paying customer in the middle of the retry window is worse than a few extra days of service, so the platform keeps you on your plan for the whole retry period. Access ends only when the subscription reaches a terminal status. What to do in the meantime is in Failed payments.
Flags that are not statuses#
| Flag | Meaning | Effect on access |
|---|---|---|
| Cancels at period end | You cancelled but the paid period has not finished | None until the period ends. The status stays active and you keep everything you paid for |
| Trial end date | The date the 14-day trial converts | None until reached |
Cancelling is always at period end, never immediate, so cancelling on day 2 of a month you have paid for leaves you on the plan for the rest of it. See Cancelling your subscription.
What each state looks like in the product#
| Situation | Plan badge and Usage tile | Premium reports | Manage Billing |
|---|---|---|---|
| Active or trialing | Your paid plan and its quota | Work normally | Opens the portal |
| Past due | Your paid plan and its quota, unchanged | Work normally | Opens the portal — update the card here |
| Terminal status | FREE with a zero quota | Refused with an upgrade message | Shows You are not on a paid subscription yet, so there is no billing to manage. |
| Plan set manually by Metric Vault | The granted plan | Work normally | Depends on whether a subscription also exists |
Metric Vault does not show your raw subscription status anywhere in the customer dashboard, and it does not display a "cancels at period end" notice. The plan badge and the credit indicator are the customer-visible signal. Support can see the live status, the renewal date, the amount and the cancel-at-period-end flag.
How a change reaches your account#
| Event | What the platform does | How fast |
|---|---|---|
| Checkout completes | Reads the plan from the new subscription and grants it | Seconds |
| Subscription created or updated | Grants the plan for an entitling status; drops to Free otherwise | Seconds |
| Subscription deleted | Drops the account to Free | Seconds |
| Reconciliation job | Re-reads every live subscription and corrects any drift | On a regular cycle, typically within about 15 minutes |
| Anything else | Recorded and ignored | — |
Two behaviors worth knowing:
- A plan granted manually by Metric Vault is protected. If our team has set your plan by hand — a comped account, a migration, a goodwill grant — subscription events and the reconciliation job will not overwrite it. Completing a new checkout does replace it, because that is an explicit purchase.
- The reconciliation job never mass-downgrades on a partial read. If it cannot read the full subscription list in one pass, it grants upgrades only and makes no downgrades at all, so a provider hiccup cannot sweep customers onto Free.
Multiple subscriptions on one account#
If an account somehow ends up with more than one live subscription, the platform resolves the highest plan among them. That is the safe outcome for access, but it does not merge or cancel anything: two subscriptions are two charges. Metric Vault does not cancel an old subscription when you check out a new plan, so if you have changed plan by buying a second one, open the billing portal and check what is live. See Upgrading and downgrading and Managing billing in the customer portal.
When the state and the product disagree#
| Symptom | Most likely explanation | Action |
|---|---|---|
| Paid, but still on Free | The event has not applied yet | Wait for the next reconciliation pass, then see My plan did not update after paying |
| Cancelled, but still have access | Cancellation is at period end | Expected. Access ends when the paid period ends |
| Card failed, but nothing changed | past_due keeps access | Expected. Update the card before retries are exhausted |
| Trial ended and access stopped | The first charge did not succeed | Check the payment method in the portal, see Failed payments |
| Plan is right in the portal, wrong in the app | Signed in with a different email address than the one on the subscription | Sign in with the email used at checkout |
The last row is the single most common cause. Your plan is held against the email address on your Metric Vault account, so a subscription bought under a different address will not appear on it.
See also
Was this article helpful?
Thanks — feedback noted for the docs team.