Subscription lifecycle in ArcenPay

A subscription is the recurring billing relationship created after an ArcenPay checkout flow succeeds. It is anchored to a plan and a wallet address, recorded on-chain, and drives the entitlement state your application reads at runtime. Understanding the subscription lifecycle helps you handle upgrades, renewals, cancellations, and access changes correctly.

Lifecycle states

A subscription moves through the following states:

Active — the customer has a valid subscription and receives the entitlements attached to the plan.
Pending plan change — the current paid access is still live, but a future downgrade or renewal-boundary change has already been scheduled.
Needs attention — renewal or billing has failed and requires follow-up from the customer.
Cancelled — future billing has stopped. Downstream access should be updated from the latest entitlement state or webhook events.

Always treat the entitlement resolution result and webhook events as the authoritative source of access state — not the last client-side screen the customer saw.

How subscriptions are activated

You can activate a subscription in two ways: Via ArcenEmbed — when a customer completes a checkout flow in the published billing surface, the subscription is activated automatically. Via client.activateSubscription() — activate programmatically from your server using the Node SDK. This is useful for provisioning flows where you need to activate a subscription outside of the standard UI.

import { ArcenClient } from "@arcenpay/node";

const client = new ArcenClient({
  apiKey: process.env.ARCENPAY_API_KEY!,
});

const activation = await client.activateSubscription({
  planId: "starter",
  paymentAccount: "0xabc...",
  company: { id: "company_123", wallet: "0xabc..." },
});

Subscription activation works on EVM, Stellar, and Solana. Autopay is set up per family: an ERC-7579 smart account with the autopay module (EVM), a shared SPL delegate (Solana), or an autopay account (Stellar). The wallet in paymentAccount is an EVM address, a Stellar account, or a Solana base58 address depending on the chain.

Supported operations

Operation	Behavior	Result mode
Buy a new subscription	Start from published checkout and finish with authoritative activation.	`activateSubscription()` success
Upgrade to a higher paid plan	Immediate prorated upgrade after on-chain config verification and, when needed, a prorated payment.	`immediate_prorated_upgrade`
Preview an upgrade before signing	Calculate the exact proration amount before any final plan-change transaction is consumed.	`immediate_prorated_upgrade_preview`
Downgrade to a lower paid plan	Always stays on the current plan until the current billing period ends in self-serve.	`period_end_downgrade`
Cancel but keep access through the current term	Schedules cancellation at period end and keeps the current paid access active.	`cancel_at_period_end`
Resume a scheduled cancellation	Clears the scheduled cancellation and restores normal renewal once billing capability is active again.	`resume_applied`

Auto-renewal

ArcenPay handles automated renewal processing. You do not need to implement renewal logic yourself. When a renewal succeeds or fails, ArcenPay emits webhook events that you can use to update your application state.

Register a webhook endpoint in the dashboard and listen for renewal events to keep your internal records in sync with billing outcomes.

Accepted vs verified vs applied

ArcenPay treats recurring billing changes as lifecycle requests:

Accepted: the request was recorded and has a durable transitionId.
Verified: required on-chain billing actions have enough confirmations.
Applied: the ledger, subscription state, invoices, and webhooks all reflect the final result.

This is why the embed may show states such as Downgrade scheduled, Pending verification, or Pending recovery instead of pretending the final billing outcome already happened.

Key webhook events

Event	When it fires
`subscription.minted`	A new subscription NFT was minted on-chain.
`subscription.renewed`	The subscription successfully renewed for another period.
`subscription.renewal_failed`	A renewal attempt failed; the subscription needs attention.
`company.plan.changed`	The company’s active plan changed (upgrade or downgrade).
`company.plan.cancelled`	The company’s plan was cancelled.

Checking subscription access

Use the React SDK for UI gating and the Node SDK for authoritative server-side checks.

import { useFlag } from "@arcenpay/react";

const enabled = useFlag("analytics_export");
if (!enabled) return <UpgradePrompt />;

const entitlement = await client.checkEntitlement("analytics_export", {
  id: "company_123",
});

if (!entitlement.enabled) {
  throw new Error("Upgrade required");
}

Use client.checkEntitlement() on the server for any access decision that controls sensitive data or billable operations. React hooks are for UI display only.

Next steps

Feature entitlements and flags — check what access a subscription grants at both the React and server layers.
Sessions and access tokens — mint short-lived tokens for server-controlled embed surfaces.

Get started

Core concepts

Guides

Integrations

Subscription lifecycle in ArcenPay

Lifecycle states

How subscriptions are activated

Supported operations

Auto-renewal

Accepted vs verified vs applied

Key webhook events

Checking subscription access

Next steps

​Lifecycle states

​How subscriptions are activated

​Supported operations

​Auto-renewal

​Accepted vs verified vs applied

​Key webhook events

​Checking subscription access

​Next steps

Lifecycle states

How subscriptions are activated

Supported operations

Auto-renewal

Accepted vs verified vs applied

Key webhook events

Checking subscription access

Next steps