Subscription and Purchase Lifecycle

Understand subscription and purchase states and how Arcalotl changes Discord access.

Arcalotl turns subscription and purchase events into Discord access, retention messages, and dashboard status. This lifecycle explains how billing changes become member-facing actions in your server.

Status reference

Status	Meaning	Access behavior
`pending`	Checkout or activation is in progress	Role is not guaranteed yet
`active`	Stripe says the subscription is active	Role should be granted
`trialing`	Stripe says the subscription is in a trial period	Role access follows the server trial setting
`past_due`	A renewal failed and payment recovery may be running	Role remains during the grace period
`cancelling`	Cancellation is scheduled for the end of the billing period	Role remains until access ends
`cancelled`	Subscription has ended	Role should be removed
`pausing`	A pause save offer was accepted and Stripe pause confirmation is pending	Role behavior follows the pause flow until Stripe confirms
`paused`	Stripe says the subscription is paused	Access can be removed when the paid period expires
`incomplete`	Initial payment needs action or has not completed	Role is not granted as active access
`incomplete_expired`	Stripe expired an incomplete initial payment	Terminal state, no automatic recovery path

Dashboard plan creation supports free trial days. By default, trialing members receive the configured Discord role. Limited-trial servers can disable trial role access from server settings.

Common transitions

Transition	Trigger
`pending` to `active`	Stripe confirms checkout or subscription activation
`active` to `past_due`	Stripe reports a failed invoice payment
`past_due` to `active`	Payment succeeds after recovery
`active` to `cancelling`	Member confirms cancellation
`cancelling` to `active`	Member reactivates before the period ends
`cancelling` to `cancelled`	Stripe confirms cancellation
`active` to `pausing`	Member accepts a pause save offer
`pausing` to `paused`	Stripe confirms pause
`active` to `active`	Term optimization changes monthly billing to annual
`active` to `active`	A related-tier switch upgrades immediately or schedules a downgrade

Downgrades keep the current subscription active until the current billing period ends. /manage shows the pending target plan while the scheduled change waits for Stripe to apply it. Buying a different tier in the same upgrade group opens the same upgrade or downgrade confirmation on the existing subscription. In /manage, higher ranked related tiers appear behind Upgrade and lower ranked related tiers appear behind Downgrade.

Role access rules

Arcalotl grants the configured Discord role when a subscription becomes active. It removes the role when access ends, when payment recovery grace expires, or when a terminal billing state requires access removal.

The bot must be able to manage the configured role. If Discord blocks role changes, billing state may be correct while Discord access needs support attention.

One-time purchase access

One-time purchases do not renew and do not move through the subscription status table above. Arcalotl grants the configured Discord role after Stripe confirms the Checkout payment.

Access can be permanent or timed:

Permanent one-time access stays active until the purchase is refunded or disputed.
Timed one-time access ends after the configured number of access days.

When timed access expires, Arcalotl removes the role unless the member still has another active subscription or one-time purchase that grants the same role.

Refunds and open disputes remove one-time access. If a dispute is won and the purchase is still otherwise valid, Arcalotl can grant the role again.

Payment recovery grace

When a renewal fails, the subscription becomes past_due. Arcalotl starts payment recovery and keeps the role during the configured grace period.

If payment is still unresolved after the grace period, Arcalotl removes role access while the payment recovery sequence continues toward recovery or exhaustion.