Crear una suscripción

post/v1/subscriptions

Crea una suscripción sobre un plan. El PSP corre el schedule (modelo delegado-nativo) y Cauril normaliza vía webhook entrante. Requiere el header Idempotency-Key. Si el primer cobro requiere SCA, la suscripción queda en incomplete y latest_invoice.payment.next_action indica la acción.

Request

BASH

curl -X POST https://api.cauril.com/v1/subscriptions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_01J...",
    "plan": "plan_01J...",
    "payment_method": "string",
    "provider": "stripe",
    "trial_days": 0,
    "metadata": {}
  }'

Parámetros

Idempotency-Keyheaderreq

string

Clave única por operación (ej. un UUID). Reintentar con la misma key replica la respuesta original.

Cuerpo CreateSubscription

customerreq	string	Id del customer.
planreq	string	Id del plan.
payment_methodreq	string	Token del método generado del lado del cliente/PSP.
provider	string	Forzar un PSP. Si se omite, se resuelve por routing.
trial_days	integer
metadata	object

Respuestas

201	Suscripción creada	Subscription
400	Error	Error
402	Error	Error
409	Error	Error
422	Error	Error

Ejemplo de respuesta · 201

JSON

{
  "object": "subscription",
  "id": "sub_01J...",
  "status": "incomplete",
  "customer_id": "cus_01J...",
  "plan_id": "plan_01J...",
  "provider": "stripe",
  "engine": "native",
  "current_period_start": "2026-06-01T12:00:00Z",
  "current_period_end": "2026-06-01T12:00:00Z",
  "cancel_at_period_end": true,
  "trial_end": null,
  "provider_subscription_id": null,
  "metadata": {},
  "latest_invoice": null,
  "created_at": "2026-06-01T12:00:00Z",
  "updated_at": "2026-06-01T12:00:00Z"
}