Subscriptions

Una Subscription representa la suscripción de un Customer a un SubscriptionPlan recurrente. Sangho gestiona automáticamente las renovaciones, los recordatorios en caso de fallo de pago y las notificaciones por correo electrónico.

Casos de uso típicos: suscripción mensual a un SaaS, acceso a una plataforma de formación, paquete de servicios recurrentes con o sin período de prueba.

Renovaciones automáticas

Sangho cobra automáticamente al Customer al final de cada período mediante el método de pago registrado. En caso de fallo, la Subscription pasa a past_due y se activan reintentos automáticos. Recibe un webhook subscription.payment_failed con cada intento fallido.

Ciclo de vida

trialing→active→past_due→paused→canceled / unpaid / expired

Estado	Significado	Acción disponible
`trialing`	Período de prueba en curso: sin cobros.	`/cancel/`, `/pause/`.
`active`	Suscripción activa: renovaciones en curso.	`/cancel/`, `/pause/`.
`past_due`	Renovación fallida: reintentos en curso.	`/cancel/` o esperar el reintento.
`paused`	Suspendida manualmente: sin cobros.	`/resume/` para reanudar.
`canceled`	Cancelada: sin cobros futuros.	`/reactivate/` si está dentro del plazo.
`unpaid`	Todos los reintentos han fallado.	Se requiere una acción manual.
`expired`	Llegada a su término (fecha de fin definida).	Crear una nueva Subscription.

Endpoints

Méthode	Endpoint	Description
POST	`/subscriptions/`	Crear una suscripción
GET	`/subscriptions/`	Listar las suscripciones
GET	`/subscriptions/{id}/`	Recuperar una suscripción
PATCH	`/subscriptions/{id}/`	Modificar una suscripción
POST	`/subscriptions/{id}/cancel/`	Cancelar
POST	`/subscriptions/{id}/reactivate/`	Reactivar tras una cancelación
POST	`/subscriptions/{id}/pause/`	Suspender los cobros
POST	`/subscriptions/{id}/resume/`	Reanudar tras una suspensión

¿Está clara esta introducción?

Esquema del objeto

ResponseObjeto Subscription

Estructura completa devuelta por todos los endpoints de este recurso.

json

{
  "id": "sub_xxxxxxxxxxxx",
  "object": "subscription",
  "app": "app_xxxxxxxx",
  "customer": "cust_3Nx8mLKZ2eZvKYlo",
  "status": "active",
  "currency": "XAF",
  "unit_amount": 9900,
  "interval": "month",
  "interval_count": 1,
  "collection_method": "charge_automatically",
  "current_period_start": "2026-03-01T00:00:00Z",
  "current_period_end": "2026-04-01T00:00:00Z",
  "trial_start": null,
  "trial_end": null,
  "canceled_at": null,
  "cancel_at_period_end": false,
  "payment_method": "meth_xxxxxxxxxxxx",
  "metadata": {},
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Crear una Subscription

Crea una suscripción recurrente para un Customer. Si se define un trial_period_days, la Subscription arranca en estado trialing y el primer cobro se aplaza.

POSTCuerpo de la solicitud

customerRequis

stringcust_...

ID del Customer que se va a suscribir. El Customer debe existir y tener una dirección de correo electrónico válida para recibir las notificaciones de renovación.

unit_amountRequis

integercentimes

Importe que se cobra en cada período de facturación, en céntimos.

Si utiliza un SubscriptionPlan, pase mejor el campo plan: el importe se heredará del plan y no tendrá que especificarlo aquí.

intervalRequis

string

Unidad del período de facturación. Valores: day, week, month, year.

interval_countOptionnel

integerdéfaut :1

Multiplicador del intervalo. Por ejemplo, interval: “month” + interval_count: 3 = facturación trimestral.

productOptionnel

stringprod_...

ID del Product asociado a esta suscripción. Permite mostrar el nombre y la imagen del producto en las facturas de renovación.

payment_methodOptionnel

stringmeth_...

ID del método de pago que se cobrará en cada renovación. Si no se indica, se utiliza el método de pago predeterminado del Customer.

El método debe pertenecer al Customer y estar activo. En los pagos con Mobile Money, el número de teléfono asociado debe ser válido y tener saldo suficiente en el momento de la renovación.

collection_methodOptionnel

stringdéfaut :charge_automatically

Modo de cobro del pago. charge_automatically cobra automáticamente el método de pago registrado. send_invoice genera una Invoice que se envía al Customer en cada renovación.

send_invoice se recomienda para las suscripciones B2B en las que el cliente prefiere pagar contra factura. El Customer recibe entonces un correo con el enlace de pago en cada período.

trial_period_daysOptionnel

integer

Duración del período de prueba gratuito en días para este suscriptor concreto. Sobrescribe el valor definido en el SubscriptionPlan.

Durante el período de prueba, la Subscription está en estado trialing y no se realiza ningún cobro. Se envía un webhook subscription.trial_will_end 3 días antes del fin de la prueba para permitir un recordatorio proactivo.

cancel_at_period_endOptionnel

booleandéfaut :false

Si es true, la Subscription se cancela automáticamente al final del período en curso. No se realizará ninguna renovación.

Útil para las cancelaciones “a final de mes”: el acceso se mantiene hasta el final del período pagado y después la Subscription pasa a canceled sin ningún cobro adicional.

metadataOptionnel

object

Datos libres: referencia interna, plan de origen, canal de captación, etc.

Los metadatos se incluyen en todos los webhooks vinculados a esta Subscription (subscription.created, subscription.canceled, subscription.payment_failed).

¿Están claros los parámetros de creación?

Crear una suscripción

bash

curl -X POST https://api.sangho.ga/v1/subscriptions/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cust_3Nx8mLKZ2eZvKYlo",
    "unit_amount": 9900,
    "interval": "month",
    "payment_method": "meth_xxxxxxxxxxxx",
    "trial_period_days": 14,
    "metadata": { "plan_tier": "growth" }
  }'

Response201 Created

La Subscription se crea. El estado es trialing si se define un trial_period_days y active en caso contrario.

json

{
  "id": "sub_xxxxxxxxxxxx",
  "object": "subscription",
  "app": "app_xxxxxxxx",
  "customer": "cust_3Nx8mLKZ2eZvKYlo",
  "status": "trialing",
  "currency": "XAF",
  "unit_amount": 9900,
  "interval": "month",
  "interval_count": 1,
  "collection_method": "charge_automatically",
  "current_period_start": "2026-03-01T00:00:00Z",
  "current_period_end": "2026-04-01T00:00:00Z",
  "trial_start": "2026-03-01T00:00:00Z",
  "trial_end": "2026-03-15T00:00:00Z",
  "canceled_at": null,
  "cancel_at_period_end": false,
  "payment_method": "meth_xxxxxxxxxxxx",
  "metadata": { "plan_tier": "growth" },
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Gestionar el ciclo de vida

Cancelar (/cancel/): pone fin a la suscripción. Pase cancel_at_period_end: true en el cuerpo para aplazar la cancelación al final del período en curso: el acceso se mantiene hasta el final.

Reactivar (/reactivate/): restaura una Subscription cancelada recientemente, siempre que no haya expirado el período de gracia. La Subscription se reanuda en active con la siguiente renovación programada.

Suspender (/pause/): suspende los cobros sin cancelar la suscripción. La Subscription pasa a paused. Útil para los clientes de vacaciones o con dificultades temporales.

Reanudar (/resume/): reanuda una Subscription suspendida. El siguiente cobro se programa en el siguiente período normal.

Cancelación inmediata frente a fin de período

Llamar a /cancel/ sin cuerpo cancela de inmediato. Pasar { cancel_at_period_end: true } permite que el suscriptor acceda al servicio hasta el final del período pagado, que es el comportamiento recomendado para una mejor experiencia del cliente.

Modificar una Subscription

Permite actualizar el método de pago, el modo de cobro o los metadatos de una Subscription activa.

PATCHCuerpo de la actualización (PATCH)

payment_methodOptionnel

stringmeth_...

Nuevo método de pago para las próximas renovaciones. Debe pertenecer al Customer.

collection_methodOptionnel

string

Cambiar el modo de cobro: charge_automatically o send_invoice.

cancel_at_period_endOptionnel

boolean

Pase true para programar una cancelación a fin de período. Pase false para anular una cancelación programada.

metadataOptionnel

object

Combinación con los metadatos existentes.

¿Está bien documentada la gestión del ciclo de vida?

Cancelar a fin de período

bash

curl -X POST https://api.sangho.ga/v1/subscriptions/sub_xxx/cancel/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "cancel_at_period_end": true }'

Suspender / Reanudar

bash

# Suspendre
curl -X POST https://api.sangho.ga/v1/subscriptions/sub_xxx/pause/ \
  -H "Authorization: Bearer sk_prod_xxxx"


# Reprendre
curl -X POST https://api.sangho.ga/v1/subscriptions/sub_xxx/resume/ \
  -H "Authorization: Bearer sk_prod_xxxx"

Response200 OK — Cancelación programada

La Subscription sigue activa hasta current_period_end y después pasa automáticamente a canceled.

Pase cancel_at_period_end: false mediante PATCH para anular una cancelación programada antes de que sea efectiva.

json

{
  "id": "sub_xxxxxxxxxxxx",
  "status": "active",
  "cancel_at_period_end": true,
  "current_period_end": "2026-04-01T00:00:00Z",
  "canceled_at": null,
  "updated_at": "2026-03-15T10:00:00Z"
}

Cambiar el método de pago

bash

curl -X PATCH https://api.sangho.ga/v1/subscriptions/sub_xxx/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method": "meth_yyyyyyyyyyyy" }'

Response200 OK — Subscription actualizada

El nuevo método de pago se utilizará a partir de la próxima renovación.

json

{
  "id": "sub_xxxxxxxxxxxx",
  "status": "active",
  "payment_method": "meth_yyyyyyyyyyyy",
  "updated_at": "2026-03-20T14:00:00Z"
}