SubscriptionPlans

Les SubscriptionPlans définissent les tarifs récurrents que vous proposez à vos clients. Chaque plan spécifie un montant, une devise et une fréquence de facturation. Un plan est ensuite associé à une ou plusieurs Subscriptions pour déclencher les prélèvements automatiques.

Cas d’usage typiques : abonnement mensuel SaaS, forfait annuel avec remise, offre trimestrielle avec période d’essai gratuite.

Montant immuable après création

Le montant d’un plan (amount) ne peut pas être modifié après création. Pour changer le tarif, créez un nouveau plan et migrez vos abonnés via PATCH /subscriptions/{id}/. Seuls le name et la description sont modifiables via PATCH.

Endpoints

Méthode	Endpoint	Description
POST	`/subscription-plans/`	Créer un plan
GET	`/subscription-plans/`	Lister les plans
GET	`/subscription-plans/{id}/`	Récupérer un plan
PATCH	`/subscription-plans/{id}/`	Modifier (nom et description uniquement)
DELETE	`/subscription-plans/{id}/`	Désactiver (impossible si abonnés actifs)

Cette introduction est-elle claire ?

Schéma de l’objet

Response Objet SubscriptionPlan

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

json

{
  "id": "plan_xxxxxxxxxxxx",
  "object": "subscription_plan",
  "name": "Plan Growth Mensuel",
  "description": "Accès complet à toutes les fonctionnalités Growth",
  "amount": 15000,
  "currency": "XAF",
  "interval": "month",
  "interval_count": 1,
  "trial_period_days": 14,
  "active": true,
  "metadata": {
    "tier": "growth"
  },
  "livemode": true,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Créer un SubscriptionPlan

Crée un nouveau plan tarifaire. Le plan est immédiatement disponible pour être associé à une Subscription.

POST Corps de la requête

name Requis

string ex : Plan Growth Mensuel

Nom du plan. Visible par le client sur les pages de paiement, les factures et les emails de renouvellement.

Choisissez un nom clair qui reflète la valeur proposée — il apparaît directement dans les communications envoyées à vos abonnés.

amount Requis

integer centimes ex : 15000

Montant prélevé à chaque période de facturation, en centimes. Ce champ est immuable après création.

Exprimez toujours en centimes. 15 000 XAF = 15000. Pour les devises à décimales (EUR, USD), 15 EUR = 1500. Pour modifier un tarif, créez un nouveau plan et migrez vos abonnés.

currency Requis

string ISO 4217 ex : XAF

Code ISO 4217 de la devise du plan. Doit correspondre à une devise activée sur votre App. Immuable après création.

interval Requis

string

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

Combiné avec interval_count, ce champ définit la fréquence exacte de facturation. Exemples : interval: “month” + interval_count: 3 = facturation trimestrielle ; interval: “year” + interval_count: 1 = facturation annuelle.

interval_count Optionnel

integer défaut : 1

Multiplicateur de l’intervalle. Détermine la fréquence réelle de facturation en combinaison avec interval.

Exemples : interval: “month”, interval_count: 1 → mensuel ; interval: “month”, interval_count: 3 → trimestriel ; interval: “month”, interval_count: 6 → semestriel.

trial_period_days Optionnel

integer ex : 14

Durée de la période d’essai gratuite en jours. Pendant cette période, aucun prélèvement n’est effectué. La Subscription passe en statut trialing jusqu’à la fin de l’essai.

Ce champ définit la période d’essai par défaut du plan. Il peut être surchargé par abonné en passant trial_period_days directement lors de la création de la Subscription.

description Optionnel

string

Description du plan. Affichée sur la page de sélection de plan et dans les emails de bienvenue.

metadata Optionnel

object

Données libres — identifiant interne, tier tarifaire, référence CRM, etc.

Les métadonnées du plan sont incluses dans les webhooks subscription.created et subscription.canceled. Utile pour identifier le tier lors du provisioning automatique d’accès.

Les paramètres du plan sont-ils clairs ?

Créer un plan mensuel avec essai

bash

curl -X POST https://api.sangho.com/v1/subscription-plans/ \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plan Growth Mensuel",
    "amount": 15000,
    "currency": "XAF",
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": 14,
    "description": "Accès complet à toutes les fonctionnalités Growth",
    "metadata": { "tier": "growth" }
  }'

Response 201 Created

Le plan est actif immédiatement et peut être associé à de nouvelles Subscriptions.

json

{
  "id": "plan_xxxxxxxxxxxx",
  "object": "subscription_plan",
  "name": "Plan Growth Mensuel",
  "description": "Accès complet à toutes les fonctionnalités Growth",
  "amount": 15000,
  "currency": "XAF",
  "interval": "month",
  "interval_count": 1,
  "trial_period_days": 14,
  "active": true,
  "metadata": { "tier": "growth" },
  "livemode": true,
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Lister les SubscriptionPlans

Retourne tous les plans de votre App, triés par date de création décroissante.

GET Paramètres de requête (query)

active Optionnel

boolean

Filtrer par statut. true retourne uniquement les plans actifs, false les plans désactivés.

currency Optionnel

string ISO 4217

Filtrer par devise. Utile si vous proposez des plans dans plusieurs devises.

interval Optionnel

string

Filtrer par intervalle de facturation : day, week, month ou year.

page Optionnel

integer défaut : 1

Numéro de page.

page_size Optionnel

integer défaut : 20

Résultats par page. Maximum : 100.

Modifier un SubscriptionPlan

Seuls le name et la description sont modifiables après création. Le amount, la currency, l’interval et l’interval_count sont immuables.

PATCH Corps de la mise à jour (PATCH)

name Optionnel

string

Nouveau nom du plan. Répercuté sur les emails de renouvellement futurs.

description Optionnel

string

Nouvelle description. Passez null pour supprimer.

metadata Optionnel

object

Fusion des métadonnées existantes.

Désactiver un SubscriptionPlan

Désactive le plan en passant active à false. Un plan désactivé ne peut plus être associé à de nouvelles Subscriptions, mais les abonnements en cours continuent de fonctionner normalement.

Impossible si abonnés actifs

La désactivation échoue avec une erreur 409 Conflict si le plan possède encore des Subscriptions en statut active ou trialing. Migrez d’abord vos abonnés vers un nouveau plan avant de désactiver l’ancien.

Les opérations sur les SubscriptionPlans sont-elles bien documentées ?

Lister les plans actifs

bash

curl "https://api.sangho.com/v1/subscription-plans/?active=true&interval=month" \
  -H "Authorization: Bearer sk_live_xxxx"

Modifier un plan

bash

curl -X PATCH https://api.sangho.com/v1/subscription-plans/plan_xxx/ \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plan Growth Mensuel — Nouveau",
    "metadata": { "tier": "growth", "legacy": null }
  }'

Response 200 OK — Plan mis à jour

json

{
  "id": "plan_xxxxxxxxxxxx",
  "object": "subscription_plan",
  "name": "Plan Growth Mensuel — Nouveau",
  "amount": 15000,
  "currency": "XAF",
  "interval": "month",
  "interval_count": 1,
  "active": true,
  "metadata": { "tier": "growth" },
  "updated_at": "2026-04-01T09:00:00Z"
}

Désactiver un plan

bash

curl -X DELETE https://api.sangho.com/v1/subscription-plans/plan_xxx/ \
  -H "Authorization: Bearer sk_live_xxxx"

Response 200 OK — Désactivé

Le plan est désactivé. Les Subscriptions existantes continuent de fonctionner jusqu'à leur résiliation.

Échoue avec 409 si des Subscriptions actives ou trialing sont encore associées à ce plan.

json

{
  "id": "plan_xxxxxxxxxxxx",
  "active": false,
  "updated_at": "2026-04-10T12:00:00Z"
}