The Subscription object

ArcenPay subscriptions are on-chain. When a subscriber activates a plan, the platform executes an EVM transaction that mints a subscription token to the payment account and begins the autopay cycle. Your backend interacts with this through a small set of endpoints and SDK methods that handle activation, entitlement checks, metered usage, plan changes, and cancellation.

Subscription object

Subscription state is tracked in the ledger and surfaced via the company detail response. Key fields:

Field	Type	Description
`tokenId`	string	On-chain subscription NFT token ID.
`txHash`	string	Transaction hash of the initial activation.
`companyId`	string	ArcenPay’s internal company ID (`cm_...`).
`planId`	string	Catalog plan ID the subscription is attached to.
`paymentAccount`	string	Wallet address (EVM, Stellar, or Solana) paying for the subscription.
`status`	string	Current subscription state (`ACTIVE`, `PAST_DUE`, `CANCELLED`).
`currentPeriodEnd`	string (ISO 8601)	When the current billing period ends.
`cancelAtPeriodEnd`	boolean	`true` when the subscription is scheduled to cancel at the next renewal.

Activate a subscription

POST /api/v1/subscriptions/activate executes the first on-chain subscription charge through the merchant signer configured on your dashboard backend.

POST /api/v1/subscriptions/activate
Authorization: Bearer sk_live_xxxxxxxx

Request body

string | number

required

The on-chain PlanFactory plan ID for the plan to activate.

string

required

The subscriber’s wallet address (EVM EOA/smart account, Stellar account, or Solana wallet). Autopay is set up per family: an ERC-7579 smart account with the autopay module (EVM), a shared SPL delegate PDA (Solana), or an autopay account (Stellar). The wallet needs sufficient token balance and allowance before calling this endpoint.

object

required

Identifies the company in your team. At least one of id, wallet, or email is required. If the company does not exist it is created automatically.

Show company fields

string

Your system’s external company ID.

string

Company wallet address (EVM, Stellar, or Solana).

string

Company email address.

string

Company display name.

object

Arbitrary key-value metadata to attach to the company record.

string

Optional. Email address to send billing confirmation to. Falls back to the company email if omitted.

Response

{
  "data": {
    "tokenId": "42",
    "txHash": "0xabc123...",
    "companyId": "cm_abc123",
    "planId": "plan_starter",
    "paymentAccount": "0xabc...",
    "recoveryTaskId": null,
    "recoveryPending": false
  }
}

string

On-chain subscription NFT token ID minted to the payment account.

string

EVM transaction hash for the initial activation charge. You can look this up on any block explorer for the configured chain.

string

ArcenPay’s internal ID for the company record that was resolved or created.

string

Catalog plan ID the subscription was activated against.

string

The normalized payment account address.

boolean

true when the on-chain transaction succeeded but the billing ledger finalization was queued for recovery (HTTP 202). The subscription is active — check back or listen for subscription.minted via webhooks.

SDK equivalent

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..." },
});

console.log(activation.txHash);

Check entitlements

Check whether a company is entitled to a feature by key:

GET /api/v1/check?key=scan
Authorization: Bearer sk_live_xxxxxxxx

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

const flag = await client.checkFlag("scan", { id: "company_123" });

Consume metered usage

For metered features, call POST /api/v1/usage/consume (or the SDK equivalent) after each unit of use. Supply an idempotencyKey to make the call safe to retry:

POST /api/v1/usage/consume
Authorization: Bearer sk_live_xxxxxxxx

{
  "featureKey": "scan",
  "company": { "id": "company_123" },
  "idempotencyKey": "scan-req-1"
}

const result = await client.consumeEntitlement({
  featureKey: "scan",
  company: { id: "company_123" },
  idempotencyKey: "scan-req-1",
});

Plan changes and cancellation

After the initial activation, plan changes and cancellations go through POST /api/v1/companies/plan and POST /api/v1/companies/unsubscribe.

Plan changes, cancellation, and resume are self-serve customer flows — they authenticate with an embed access token (from identify()) and run inside ArcenEmbed. They are not provider API-key calls. If your backend must trigger a plan change programmatically, workflow through your customer’s normal checkout/portal flow or do it from the dashboard’s customer view.

Operation	Endpoint	Mode
Upgrade preview	`POST /api/v1/companies/plan/preview`	`immediate_prorated_upgrade_preview`
Immediate paid upgrade	`POST /api/v1/companies/plan` with tx hashes	`immediate_prorated_upgrade`
Scheduled downgrade	`POST /api/v1/companies/plan`	`period_end_downgrade`
Cancel at period end	`POST /api/v1/companies/unsubscribe`	`cancel_at_period_end`
Resume a scheduled cancellation	`POST /api/v1/companies/resume`	`resume_applied`

Preview an upgrade (no charge):

{
  "planId": "plan_pro"
}

Execute an immediate prorated upgrade:

{
  "planId": "plan_pro",
  "autopayConfigTxHash": "0x...",
  "paymentTxHash": "0x...",
  "accessChangeTxHash": "0x..."
}

Schedule a downgrade at next renewal:

{
  "planId": "plan_starter",
  "autopayConfigTxHash": "0x..."
}

Resume a scheduled cancellation:

{}

Lifecycle response contract

Plan changes, cancellation, and resume now return the same core lifecycle fields:

Field	Meaning
`transitionId`	Durable `SubscriptionChangeRequest` id for the lifecycle action.
`changeType`	`upgrade`, `downgrade`, `cancellation`, `resume`, or `billing_period_change`.
`stage`	`requested`, `pending_verification`, `pending_recovery`, `applied`, `failed`, or `reverted`.
`scheduled`	`true` for period-end actions like downgrade or cancellation.
`effectiveAt`	ISO timestamp for the scheduled/apply point when known.
`pendingVerification`	`true` when the on-chain step exists but still needs more confirmations.
`pendingRecovery`	`true` when chain state is good but backend follow-up is still recovering.
`alreadyScheduled`	`true` when ArcenPay reused an equivalent open lifecycle request instead of creating a duplicate.

Customer action accepted is not the same as financially final. For recurring paid subscriptions, ArcenPay only treats a change as fully applied after verified chain state plus backend ledger follow-up.

Subscription lifecycle events

ArcenPay emits webhook events as the subscription moves through its lifecycle. Listen for these on your webhook endpoint:

Event	When it fires
`subscription.minted`	A new subscription NFT was minted (initial activation).
`subscription.renewed`	The autopay module collected the renewal charge successfully.
`subscription.renewal_failed`	A renewal attempt failed; the subscription entered a grace period.
`subscription.cancelled`	The subscription was cancelled at the applied lifecycle stage.
`company.plan.changed`	The company’s active plan changed (upgrade or downgrade applied).
`company.plan.cancelled`	The company’s plan was cancelled.

Auto-renewal

No action is required from your backend to handle renewals. The on-chain autopay module collects the renewal charge automatically at each billing interval. ArcenPay processes the resulting chain events and emits subscription.renewed (or subscription.renewal_failed on failure). You only need to listen for these events if you want to react to renewal outcomes — for example, sending a receipt email or updating your own billing records.

Get started

Credentials

Companies

Users

Events

Access control

Features

Subscriptions

Checkout sessions

Payment links

Invoices

Autonomous agents

Escrow

Mandates

Coupons

zkTLS proofs

Public specs

The Subscription object

Subscription object

Activate a subscription

Request body

Response

SDK equivalent

Check entitlements

Consume metered usage

Plan changes and cancellation

Lifecycle response contract

Subscription lifecycle events

Auto-renewal

​Subscription object

​Activate a subscription

​Request body

​Response

​SDK equivalent

​Check entitlements

​Consume metered usage

​Plan changes and cancellation

​Lifecycle response contract

​Subscription lifecycle events

​Auto-renewal

Subscription object

Activate a subscription

Request body

Response

SDK equivalent

Check entitlements

Consume metered usage

Plan changes and cancellation

Lifecycle response contract

Subscription lifecycle events

Auto-renewal