Checkout links

POST /v1/checkout-links (scope checkout:write) creates a real checkout session for a specific buyer. Identify the buyer with a connected platform identity, an existing Arcalotl member ID, or your own namespaced user ID.

For an operator-controlled application, follow the complete External entitlements guide.

Request

POST /v1/checkout-links
Authorization: Bearer arclt_live_...
Content-Type: application/json
Idempotency-Key: a-client-generated-unique-string

{
  "tier_id": "tier_abc123",
  "plan_id": "plan_monthly",
  "subject": {
    "external": {
      "namespace": "production",
      "external_user_id": "usr_7f921"
    }
  },
  "client_reference_id": "order_8Z4P1",
  "return_url": "https://community.example.com/billing/complete"
}

• tier_id (required): the plan tier to sell.
• subject (required): exactly one buyer identity. Send an existing member_id, a namespaced external identity you own, or a connected platform identity.
• plan_id (optional): required only when the tier has more than one active billing plan; omit it when there is exactly one.
• client_reference_id (optional): your order or checkout-attempt ID. It is returned in later entitlement source metadata.
• return_url (required for external subjects): an HTTPS page in your app. Treat it as navigation only, never as payment confirmation.
• discount_code (optional): a community discount code to apply to the checkout. Case-insensitive. Invalid or ineligible codes fail the request with 422 discount_invalid.
• Idempotency-Key (optional but recommended): makes a retry safe. See Idempotency.

Response

{
  "checkout_id": "cs_01JMZX9E7P",
  "member_id": "mem_01JMZX1Z7D",
  "url": "https://checkout.stripe.com/c/pay/cs_...",
  "expires_at": "2026-08-01T12:00:00Z"
}

The response also includes checkout_id, the canonical Arcalotl member_id, and expires_at when reported by the provider. A platform-identity checkout uses the Arcalotl-hosted surface; an external-subject checkout uses the provider-hosted surface and an HTTPS return_url you supply.

Eligibility

Checkout link creation fails with a 422 or 409 problem (see Errors) when:

• the tier does not exist or is not active (not_found)
• the community has no active payment provider configuration (payment_config_inactive)
• the tier has multiple plans and plan_id was omitted (plan_required)
• the community has no configuration for the requested platform (platform_not_connected; platform subjects only)
• the buyer is already subscribed or already purchased this tier, or a plan switch is required instead of a new checkout (not_eligible)

Retry only after fixing the underlying condition; retrying an eligibility failure with the same request will fail the same way.