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

ResponseObjet 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.

POSTCorps de la requête

nameRequis

stringex :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.

amountRequis

integercentimesex :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.

currencyRequis

stringISO 4217ex :XAF

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

intervalRequis

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_countOptionnel

integerdé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_daysOptionnel

integerex :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.

descriptionOptionnel

string

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

metadataOptionnel

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.ga/v1/subscription-plans/ \
  -H "Authorization: Bearer sk_prod_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" }
  }'

Response201 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.

GETParamètres de requête (query)

activeOptionnel

boolean

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

currencyOptionnel

stringISO 4217

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

intervalOptionnel

string

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

pageOptionnel

integerdéfaut :1

Numéro de page.

page_sizeOptionnel

integerdé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.

PATCHCorps de la mise à jour (PATCH)

nameOptionnel

string

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

descriptionOptionnel

string

Nouvelle description. Passez null pour supprimer.

metadataOptionnel

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.ga/v1/subscription-plans/?active=true&interval=month" \
  -H "Authorization: Bearer sk_prod_xxxx"

Modifier un plan

bash

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

Response200 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.ga/v1/subscription-plans/plan_xxx/ \
  -H "Authorization: Bearer sk_prod_xxxx"

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