Gestión de suscripciones mediante la API

Esta guía describe el flujo completo para crear y gestionar suscripciones recurrentes mediante la API de Sangho, desde la creación del plan hasta la gestión del ciclo de vida.

Flujo de alta en una suscripción

1. Cree un Customer para el suscriptor
2. Recopile un método de pago (PaymentIntent con confirm: true)
3. Cree la Subscription vinculando Customer, unit_amount, interval y PaymentMethod
4. Escuche subscription.created para confirmar la activación
5. Gestione los eventos subscription.trial_ending y subscription.past_due

Gestión de los fallos de pago (Dunning)

Sangho reintenta automáticamente los pagos fallidos según este calendario: D+3, D+7, D+14. Tras 3 fallos, la suscripción pasa al estado unpaid. En cada intento se emite el evento subscription.past_due.

Modificar una suscripción

Para modificar el importe o el método de pago, utilice PATCH: /subscriptions/{id}/. Para suspenderla temporalmente, utilice POST: /subscriptions/{id}/pause/.

Flujo completo

bash

# 1. Créer le customer
curl -X POST https://api.sangho.ga/v1/customers/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "abonne@example.com", "name": "Jean Ondo"}'
# 2. Créer l'abonnement
curl -X POST https://api.sangho.ga/v1/subscriptions/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cust_xxx",
    "unit_amount": 9900,
    "interval": "month",
    "trial_period_days": 7
  }'