Subscription Lifecycle
Understand subscription states and how Arcalotl changes Discord access.
Arcalotl turns subscription 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 behavior depends on server configuration |
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 |
Arcalotl can receive trialing from Stripe, but public plan creation does not
expose trial setup yet.
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 |
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.
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.