Gestion des abonnements via l’API

Ce guide décrit le flux complet pour créer et gérer des abonnements récurrents via l’API Sangho, de la création du plan à la gestion du cycle de vie.

Flux d’inscription à un abonnement

1. Créez un Customer pour l’abonné
2. Collectez une méthode de paiement (PaymentIntent avec confirm: true)
3. Créez la Subscription en liant Customer, unit_amount, interval et PaymentMethod
4. Écoutez subscription.created pour confirmer l’activation
5. Gérez les événements subscription.trial_ending, subscription.past_due

Gestion des échecs de paiement (Dunning)

Sangho retente automatiquement les paiements échoués selon ce calendrier : J+3, J+7, J+14. Après 3 échecs, l’abonnement passe en statut unpaid. À chaque tentative, l’événement subscription.past_due est émis.

Modifier un abonnement

Pour modifier le montant ou la méthode de paiement, utilisez PATCH: /subscriptions/{id}/. Pour suspendre temporairement, utilisez POST: /subscriptions/{id}/pause/.

Flux complet

bash

# 1. Créer le customer
curl -X POST https://api.sangho.com/v1/customers/ \
  -H "Authorization: Bearer sk_live_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.com/v1/subscriptions/ \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cust_xxx",
    "unit_amount": 9900,
    "interval": "month",
    "trial_period_days": 7
  }'