Billing API

Endpoints clave para creación de checkout, confirmación de suscripción y portal de cliente.

reference • updated 2026-03-15

Objetivo

Operar el ciclo completo de facturación recurrente: iniciar checkout, confirmar estado post-pago y habilitar autoservicio con trazabilidad por organización.

Endpoints y contrato operativo

Endpoint	Cuándo usar	Requisitos clave
`POST /v1/billing/subscription-checkouts`	iniciar suscripción o upgrade	token Bearer, plan válido, `Idempotency-Key`
`POST /v1/billing/subscriptions/{subscription_id}/confirm`	reconciliar estado tras retorno de checkout	`subscription_id` válido y contexto de organización
`POST /v1/billing/customer-portal/sessions`	abrir gestión self-service	cliente asociado y perfil autorizado

Flujo recomendado

11) Crear checkout
Genera sesión con plan, ciclo y contexto de organización. Guarda checkoutSessionId.
22) Redirigir usuario
Envía al usuario a checkoutUrl y evita doble submit en frontend.
33) Confirmar estado
Tras callback/retorno, llama .../confirm para cerrar estado de forma determinista.
44) Exponer portal
Genera sesiones de portal solo para perfiles permitidos.

Ejemplo de creación de checkout

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"
}

Idempotencia, reintentos y consistencia

Reutiliza la misma Idempotency-Key para la misma operación lógica.
Aplica retry exponencial con jitter en errores transitorios (429, 5xx).
No asumas éxito solo por el redirect; confirma estado final por endpoint y eventos.

Errores frecuentes

Código	Causa típica	Acción recomendada
`401`	token inválido/expirado	renovar credencial y reintentar
`403`	scope insuficiente	revisar permisos del token para billing
`409`	conflicto idempotente	reutilizar resultado original
`422`	payload inconsistente	corregir plan/ciclo/organización

Checklist de go-live

Flujo completo validado en mode=test sin estados pendientes.
Alertas activas para fallos de confirmación y picos de retries.
Portal limitado por perfil con trazabilidad de acceso.