Feature entitlements and flags

ArcenPay resolves access from the commercial state you manage in the dashboard: active plans, add-ons, overrides, and usage-aware entitlement rules. Rather than hardcoding plan logic in your application, you read the resolved answer from the SDK. This means your access control stays in sync with plan changes automatically, without a code deploy.

Entitlements vs. feature flags

Feature flags are boolean on/off access checks tied to a feature key. A flag answers a single question: does this company currently have access to this feature? Entitlements carry richer state — they include the enabled status, remaining usage quota, and other metadata associated with a feature on the active plan. Use entitlements when you need to show usage limits or enforce metered consumption.

How access is resolved

ArcenPay evaluates access in the following order:

Company-specific overrides are checked first.
Active subscription plan entitlements are applied next.
Purchased add-ons and one-time grants are merged in.
Optional usage rules or traits can further refine the final result.

Your application always receives the final resolved answer — you do not need to replicate this logic.

Checking access in React

The React SDK provides hooks for reading flags and entitlements inside your components.

import {
  useEntitlement,
  useFlag,
  useFlags,
  useConsumeEntitlement,
  useTrack,
} from "@arcenpay/react";

const scanEnabled = useFlag("scan");
const flags = useFlags(["scan", "export-pdf"]);
const entitlement = useEntitlement(walletAddress, "scan");
const { consume } = useConsumeEntitlement();
const { track } = useTrack();

Hook	Returns	Use case
`useFlag(key)`	`boolean`	Gate a UI element by feature key.
`useFlags(keys)`	`Record<string, boolean>`	Check multiple flags at once.
`useEntitlement(wallet, key)`	Entitlement object	Read enabled status and usage quota.
`useConsumeEntitlement()`	`{ consume }`	Decrement a usage entitlement.
`useTrack()`	`{ track }`	Record a metered usage event.

A typical gating pattern in a component:

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

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

React hooks reflect the customer’s current session state. They are suitable for UI gating but should not be used as the sole guard on sensitive or billable server operations.

Consuming entitlements in React

Call consume() when the customer performs an action that should decrement a usage-based entitlement:

const { consume } = useConsumeEntitlement();

await consume("scan");

Tracking metered usage in React

Use useTrack to emit a usage event without directly consuming an entitlement counter:

const { track } = useTrack();

await track("scan_started", { source: "dashboard" });

Checking access on the server

Use the Node SDK to enforce access in your API routes and backend handlers. Server-side checks are authoritative and should guard any operation that is sensitive, billable, or has side effects.

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

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

// Check a boolean feature flag
const flag = await client.checkFlag("scan", { id: "company_123" });

// Check a full entitlement with usage state
const entitlement = await client.checkEntitlement("scan", {
  id: "company_123",
});

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

Consuming entitlements on the server

When a billable operation completes on the server, consume the entitlement with an idempotency key to prevent double-counting:

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

Always provide a unique idempotencyKey per logical operation. This ensures that retries or duplicate requests do not consume additional quota.

Using FeatureFlagGuard

The React SDK exports a FeatureFlagGuard component that conditionally renders children based on a flag:

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

<FeatureFlagGuard featureKey="export-pdf" walletAddress={walletAddress}>
  <ExportButton />
</FeatureFlagGuard>

Next steps

Subscriptions — understand the lifecycle behind entitlement state.
Plans — see how plan definitions control which entitlements are granted.

Get started

Core concepts

Guides

Integrations

Feature entitlements and flags

Entitlements vs. feature flags

How access is resolved

Checking access in React

Consuming entitlements in React

Tracking metered usage in React

Checking access on the server

Consuming entitlements on the server

Using FeatureFlagGuard

Next steps

​Entitlements vs. feature flags

​How access is resolved

​Checking access in React

​Consuming entitlements in React

​Tracking metered usage in React

​Checking access on the server

​Consuming entitlements on the server

​Using FeatureFlagGuard

​Next steps

Entitlements vs. feature flags

How access is resolved

Checking access in React

Consuming entitlements in React

Tracking metered usage in React

Checking access on the server

Consuming entitlements on the server

Using FeatureFlagGuard

Next steps