Billing API

Core endpoints for checkout creation, subscription confirmation, and customer portal.

reference • updated 2026-03-15

Goal

Operate the full recurring billing lifecycle: start checkout, confirm post-payment state, and provide self-service access with organization-level traceability.

Endpoints and operational contract

Endpoint	When to use	Key requirements
`POST /v1/billing/subscription-checkouts`	start a new subscription or upgrade	Bearer token, valid plan, `Idempotency-Key`
`POST /v1/billing/subscriptions/{subscription_id}/confirm`	reconcile final state after checkout return	valid `subscription_id`, organization context
`POST /v1/billing/customer-portal/sessions`	open self-service plan/payment management	mapped customer and authorized role

Recommended flow

11) Create checkout
Create a session with plan, billing cycle, and organization context. Persist checkoutSessionId.
22) Redirect user
Send the user to checkoutUrl and prevent duplicate submit in the frontend.
33) Confirm state
After callback/return, call .../confirm to close state deterministically.
44) Expose portal safely
Generate portal sessions only for approved profiles.

Checkout creation example

bash

curl -X POST https://api.beacon.pt/v1/billing/subscription-checkouts \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chk_<operation_id>" \
  -d '{
    "organizationId": "<organization_id>",
    "plan": "plus",
    "billingCycle": "monthly",
    "mode": "test"
  }'

json

{
  "checkoutSessionId": "cs_123",
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_123",
  "expiresAt": "2026-03-15T10:30:00Z"
}

Idempotency, retries, and consistency

Reuse the same Idempotency-Key for the same logical operation.
Apply exponential backoff + jitter for transient failures (429, 5xx).
Do not assume success from redirect alone; final state must be confirmed by endpoint and events.

Frequent errors

Code	Typical cause	Recommended action
`401`	invalid/expired token	renew credentials and retry
`403`	insufficient scope	review token permissions for billing
`409`	idempotency conflict	reuse original result, avoid duplicate operations
`422`	inconsistent payload	fix plan/cycle/organization values

Go-live checklist

Full test flow passes in mode=test with no pending states.
Alerts configured for confirmation failures and retry spikes.
Portal access restricted by role with audit trail.