Subscriptions

Une Subscription représente l’abonnement d’un Customer à un SubscriptionPlan récurrent. Sangho gère automatiquement les renouvellements, les relances en cas d’échec de paiement et les notifications par email.

Cas d’usage typiques : abonnement SaaS mensuel, accès à une plateforme de formation, forfait de services récurrents avec ou sans période d’essai.

Renouvellements automatiques

Sangho prélève automatiquement le Customer à chaque fin de période via la méthode de paiement enregistrée. En cas d’échec, la Subscription passe en past_due et des retries automatiques sont déclenchés. Vous recevez un webhook subscription.payment_failed à chaque tentative échouée.

Cycle de vie

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

Statut	Signification	Action disponible
`trialing`	Période d'essai en cours — aucun prélèvement.	`/cancel/`, `/pause/`.
`active`	Abonnement actif — renouvellements en cours.	`/cancel/`, `/pause/`.
`past_due`	Renouvellement échoué — retries en cours.	`/cancel/` ou attendre le retry.
`paused`	Suspendu manuellement — aucun prélèvement.	`/resume/` pour reprendre.
`canceled`	Résilié — aucun futur prélèvement.	`/reactivate/` si dans le délai.
`unpaid`	Tous les retries ont échoué.	Action manuelle requise.
`expired`	Arrivé à terme (date de fin définie).	Créer une nouvelle Subscription.

Endpoints

Méthode	Endpoint	Description
POST	`/subscriptions/`	Créer un abonnement
GET	`/subscriptions/`	Lister les abonnements
GET	`/subscriptions/{id}/`	Récupérer un abonnement
PATCH	`/subscriptions/{id}/`	Modifier un abonnement
POST	`/subscriptions/{id}/cancel/`	Résilier
POST	`/subscriptions/{id}/reactivate/`	Réactiver après résiliation
POST	`/subscriptions/{id}/pause/`	Suspendre les prélèvements
POST	`/subscriptions/{id}/resume/`	Reprendre après suspension

Cette introduction est-elle claire ?

Schéma de l’objet

Response Objet Subscription

Structure complète retournée par tous les endpoints de cette ressource.

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

Créer une Subscription

Crée un abonnement récurrent pour un Customer. Si un trial_period_days est défini, la Subscription démarre en statut trialing et le premier prélèvement est différé.

POST Corps de la requête

customer Requis

string cust_...

ID du Customer à abonner. Le Customer doit exister et avoir une adresse email valide pour recevoir les notifications de renouvellement.

unit_amount Requis

integer centimes

Montant prélevé à chaque période de facturation, en centimes.

Si vous utilisez un SubscriptionPlan, passez plutôt le champ plan — le montant sera hérité du plan et vous n’aurez pas à le spécifier ici.

interval Requis

string

Unité de la période de facturation. Valeurs : day, week, month, year.

interval_count Optionnel

integer défaut : 1

Multiplicateur de l’intervalle. Par exemple, interval: “month” + interval_count: 3 = facturation trimestrielle.

product Optionnel

string prod_...

ID du Product associé à cet abonnement. Permet d’afficher le nom et l’image du produit sur les factures de renouvellement.

payment_method Optionnel

string meth_...

ID de la méthode de paiement à débiter à chaque renouvellement. Si non fourni, la méthode de paiement par défaut du Customer est utilisée.

La méthode doit appartenir au Customer et être active. Pour les paiements Mobile Money, le numéro de téléphone associé doit être valide et suffisamment approvisionné au moment du renouvellement.

collection_method Optionnel

string défaut : charge_automatically

Mode de collecte du paiement. charge_automatically prélève automatiquement la méthode de paiement enregistrée. send_invoice génère une Invoice envoyée au Customer à chaque renouvellement.

send_invoice est recommandé pour les abonnements B2B où le client préfère régler sur facture. Le Customer reçoit alors un email avec le lien de paiement à chaque période.

trial_period_days Optionnel

integer

Durée de la période d’essai gratuite en jours pour cet abonné spécifique. Surcharge la valeur définie sur le SubscriptionPlan.

Pendant la période d’essai, la Subscription est en statut trialing et aucun prélèvement n’est effectué. Un webhook subscription.trial_will_end est envoyé 3 jours avant la fin de l’essai pour permettre une relance proactive.

cancel_at_period_end Optionnel

boolean défaut : false

Si true, la Subscription est automatiquement résiliée à la fin de la période en cours. Aucun renouvellement ne sera effectué.

Utile pour les résiliations “à la fin du mois” : l’accès est maintenu jusqu’à la fin de la période payée, puis la Subscription passe en canceled sans prélèvement supplémentaire.

metadata Optionnel

object

Données libres — référence interne, plan d’origine, canal d’acquisition, etc.

Les métadonnées sont incluses dans tous les webhooks liés à cette Subscription (subscription.created, subscription.canceled, subscription.payment_failed).

Les paramètres de création sont-ils clairs ?

Créer un abonnement

bash

curl -X POST https://api.sangho.com/v1/subscriptions/ \
  -H "Authorization: Bearer sk_live_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" }
  }'

Response 201 Created

La Subscription est créée. Le statut est trialing si un trial_period_days est défini, active sinon.

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

Gérer le cycle de vie

Résilier (/cancel/) : met fin à l’abonnement. Passez cancel_at_period_end: true dans le corps pour différer la résiliation à la fin de la période en cours — l’accès est maintenu jusqu’au bout.

Réactiver (/reactivate/) : restaure une Subscription récemment annulée, sous réserve que la période de grâce ne soit pas expirée. La Subscription reprend en active avec le prochain renouvellement planifié.

Suspendre (/pause/) : suspend les prélèvements sans résilier l’abonnement. La Subscription passe en paused. Utile pour les clients en congé ou en difficulté temporaire.

Reprendre (/resume/) : reprend une Subscription suspendue. Le prochain prélèvement est planifié à la prochaine période normale.

Résiliation immédiate vs. fin de période

Appeler /cancel/ sans corps résilie immédiatement. Passer { cancel_at_period_end: true } laisse l’abonné accéder au service jusqu’à la fin de la période payée — comportement recommandé pour une meilleure expérience client.

Modifier une Subscription

Permet de mettre à jour la méthode de paiement, le mode de collecte ou les métadonnées d’une Subscription active.

PATCH Corps de la mise à jour (PATCH)

payment_method Optionnel

string meth_...

Nouvelle méthode de paiement pour les prochains renouvellements. Doit appartenir au Customer.

collection_method Optionnel

string

Changer le mode de collecte : charge_automatically ou send_invoice.

cancel_at_period_end Optionnel

boolean

Passer true pour programmer une résiliation en fin de période. Passer false pour annuler une résiliation programmée.

metadata Optionnel

object

Fusion des métadonnées existantes.

La gestion du cycle de vie est-elle bien documentée ?

Résilier à la fin de période

bash

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

Suspendre / Reprendre

bash

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


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

Response 200 OK — Résiliation programmée

La Subscription reste active jusqu'à current_period_end, puis passe automatiquement en canceled.

Passez cancel_at_period_end: false via PATCH pour annuler une résiliation programmée avant qu'elle ne soit effective.

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

Changer la méthode de paiement

bash

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

Response 200 OK — Subscription mise à jour

La nouvelle méthode de paiement sera utilisée dès le prochain renouvellement.

json

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