External entitlements
Sell access to your own app through Arcalotl. Checkout, plan changes, cancellations, and a member portal over one API key, with three webhooks telling you who has access.
Use this when your own application decides who gets in (a web app, a SaaS, a game server) and Arcalotl handles checkout, billing, plan changes, and cancellations. You do not need Discord or any other community platform. Everything below runs on the public API with one API key.
If Arcalotl should grant access on a connected platform such as Discord or Telegram, you do not need this guide: configure an entitlement's platform benefits and Arcalotl applies them itself.
How it works
- Create your plans in the dashboard. One entitlement per access level,
with a stable key such as
pro. Leave platform benefits empty. - Start checkout with your own user id. The response gives you the
Arcalotl
member_idand a checkout page URL. Store the id, redirect the user. - Listen to three webhooks.
member.entitlement.granted,updated, andrevokedcarry your user id and the entitlement key. Set the user's plan from the key. - Let members manage billing. Either call the API from your own buttons (switch plan, cancel, reactivate) or send them to the member portal with one link.
- Reconcile after downtime from the events feed and the member's entitlements.
Your API key needs checkout:write, members:read, members:write,
subscriptions:read, subscriptions:write, and webhooks:write. Create it
under Developers -> API Keys.
1. Model your plans
Create one entitlement per paid level in the dashboard and give it a stable
external key you will match on, for example foundation, collective,
studio. Attach the entitlement to a tier with its billing plans (monthly,
annual). No platform benefits are needed: the entitlement exists so the
webhooks can name it.
Read the ids you will need once:
GET /v1/plans
Authorization: Bearer arclt_live_...Each tier carries id (the tier_id) and its plans with their plan_id.
2. Start checkout with your user id
When a signed-in user clicks Upgrade, create a checkout link from your backend. Identify the buyer with a namespace and your own user id, and pass the page in your app they should come back to.
POST /v1/checkout-links
Authorization: Bearer arclt_live_...
Content-Type: application/json
Idempotency-Key: checkout-usr_7f921-2026-09-15T10:00:00Z
{
"tier_id": "tier_abc123",
"plan_id": "plan_monthly",
"subject": {
"external": { "namespace": "production", "external_user_id": "usr_7f921" }
},
"return_url": "https://app.example.com/settings/billing"
}{
"checkout_id": "cs_01JMZX9E7P",
"member_id": "mem_01JMZX1Z7D",
"url": "https://www.arcalotl.com/checkout/eyJhbGci...",
"expires_at": "2026-09-16T10:00:00Z"
}Store member_id next to your user, then redirect the browser to url.
That is the Arcalotl checkout page; it links back to your return_url, and
after payment the buyer lands on it with checkout_id=<checkout_id>
appended. Show a "activating" state there and wait for the webhook. Never
treat the redirect as proof of payment.
The namespace keeps environments apart (production, staging) and is
case-insensitive; the user id is yours and case-sensitive. Closing the tab
creates nothing: the same call again is safe, with a new Idempotency-Key.
3. Listen to three webhooks
Create a webhook endpoint (dashboard Developers -> Webhooks, or POST /v1/webhooks/endpoints) subscribed to:
member.entitlement.granted: the user now holds the entitlement.member.entitlement.updated: still held; its sources or identities changed.member.entitlement.revoked: the user no longer holds it.
Each event carries your user id, the entitlement key, and a revision number:
{
"id": "evt_9f2c4b1e5a7d4c0f8b3a2d1e6f5c4b3a",
"type": "member.entitlement.granted",
"data": {
"member": {
"id": "mem_01JMZX1Z7D",
"external_subjects": [
{ "namespace": "production", "external_user_id": "usr_7f921" }
]
},
"entitlement": {
"key": "foundation",
"status": "active",
"revision": 4,
"sources": [
{ "type": "subscription", "id": "sub_01JMZX47H8", "status": "active" }
]
}
}
}The handler is three lines of logic:
- Verify the signature and skip an envelope
idyou already processed. - Find your user by
member.idor the external subject. - If
revisionis newer than what you stored:grantedorupdatedwithstatus: activesets the plan named bykey;revokedclears it.
Plan switches arrive the same way: the old key is revoked and the new key is granted. See Webhooks for signature verification and retries.
4. Let members manage billing
You have two options, and they combine.
Your own buttons. Read the plans a subscription can move to, then switch:
GET /v1/subscriptions/{subscription_id}/switch-options{
"same_tier": [],
"upgrades": [
{
"plan_id": "plan_collective_monthly",
"tier_id": "tier_collective",
"amount_cents": 19900,
"currency": "usd",
"interval": "month",
"trial_days": 0
}
],
"downgrades": []
}POST /v1/subscriptions/{subscription_id}/switch
Idempotency-Key: switch-usr_7f921-2026-09-15T10:05:00Z
{ "plan_id": "plan_collective_monthly" }Upgrades and same-tier changes apply immediately with proration. A
downgrade is scheduled for the end of the period and shows on the
subscription as scheduled_plan_id and scheduled_at; POST .../cancel-scheduled-switch drops it. POST .../cancel schedules a
period-end cancellation and POST .../reactivate undoes it. The
subscription id comes from GET /v1/subscriptions?member_id=mem_....
The member portal. For card updates, invoices, and everything above in one place, mint a portal link and redirect the signed-in user to it:
POST /v1/members/{member_id}/portal-sessions
{ "return_url": "https://app.example.com/settings/billing" }{
"url": "https://www.arcalotl.com/auth/portal/handoff/...",
"expires_at": "2026-09-15T10:20:00Z"
}The link signs that member in, scoped to your community, for ten minutes. The portal offers "Back to app.example.com".
5. Reconcile after downtime
Webhooks are the signal, not your only source of truth. After an outage, or on a schedule:
GET /v1/events?type=member.entitlement.granted,member.entitlement.updated,member.entitlement.revokedfrom your last cursor.- For each member touched,
GET /v1/members/{member_id}/entitlementsand replace what you stored.
You can also answer "does this user have access right now" directly:
GET /v1/entitlements/check?namespace=production&external_user_id=usr_7f921{
"entitled": true,
"entitlements": [{ "key": "foundation", "status": "active" }]
}Users who bought somewhere else
A member who subscribed through a bot has no external subject yet. When they sign into your app and you know who they are (for example through a Discord login), find them and attach your id:
GET /v1/members/lookup?platform=discord&platform_uid=218421075025461248POST /v1/members/{member_id}/external-subjects
{ "namespace": "production", "external_user_id": "usr_7f921" }Every active entitlement is republished as member.entitlement.updated
carrying the new subject, so your webhook handler picks it up without a
resync.