Subscription and Purchase Lifecycle

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

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

Status reference

Status	Meaning	Access behavior
`pending`	Checkout or activation is in progress	Role is not guaranteed yet
`active`	The subscription is active and paid	Role should be granted
`trialing`	The subscription is in a free 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 the pause is being applied	Role behavior follows the pause flow until it is confirmed
`paused`	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`	The initial payment expired without completing	Terminal state, no automatic recovery path

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

Common transitions

Transition	Trigger
`pending` to `active`	Checkout completes and the subscription activates
`active` to `past_due`	A renewal payment fails
`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`	The billing period ends and the cancellation completes
`active` to `pausing`	Member accepts a pause save offer
`pausing` to `paused`	The pause takes effect
`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 to be applied. 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 platform 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 or Fluxer blocks role changes, billing state may be correct while platform 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 platform role as soon as the purchase payment is confirmed.

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.