Abonnements

Bêta

Fonctionnalité en cours de déploiement. L'interface décrite ici est celle de la prochaine livraison : elle peut encore évoluer, et n'est pas forcément activée sur votre tenant.

À quoi ça sert

Pour un abonnement, votre client paie la première échéance sur la page de paiement. Son moyen de paiement est alors enregistré, et la plateforme débite elle-même chaque échéance suivante, puis émet la facture correspondante. Vous n'avez rien à déclencher.

Prérequis

subscription dans billingModes de votre compte de paiement.
Un jeton avec les scopes carts (créer l'abonnement) et subscriptions (le gérer).

1. Créer le panier d'abonnement

Même appel que pour un paiement ponctuel, avec "mode": "subscription" et la périodicité :

curl -s -X POST https://billing-api.dev.stackngo.fr/v1/carts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "subscription",
    "currency": "EUR",
    "subscription": { "interval": "month", "interval_count": 1 },
    "customer": {
      "external_ref": "user-381",
      "name": "Dupont Conseil",
      "email": "compta@dupont.example",
      "address": { "line1": "3 place Bellecour", "postal_code": "69002", "city": "Lyon", "country": "FR" }
    },
    "lines": [
      { "label": "Offre Pro", "quantity": "1", "unit_amount": "49.00", "tax_category": "S", "tax_rate": "20.00" }
    ],
    "success_url": "https://shop.acme.example/bienvenue",
    "tags": { "shop": "saas", "plan": "pro" }
  }'

`subscription`	Valeurs
`interval`	`day`, `week`, `month`, `year`
`interval_count`	1 à 36 (défaut 1) : `"interval": "month", "interval_count": 3` = tous les trimestres

La réponse est un panier avec son payment_url, comme pour un paiement ponctuel. Une fois payé, le panier porte subscription_id.

Ce que vous obtenez

curl -s https://billing-api.dev.stackngo.fr/v1/subscriptions/sub_01J9ZR2B6C7D8E9F0G1H \
  -H "Authorization: Bearer $TOKEN"

{
  "id": "sub_01J9ZR2B6C7D8E9F0G1H",
  "customer_id": "cus_01J9ZR1A2B3C4D5E6F7G",
  "status": "active",
  "currency": "EUR",
  "lines": [
    { "label": "Offre Pro", "quantity": "1", "unit_amount": "49.00", "tax_category": "S", "tax_rate": "20.00", "amount": "49.00" }
  ],
  "interval": "month",
  "interval_count": 1,
  "current_period_start": "2026-10-08T10:20:00Z",
  "current_period_end": "2026-11-08T10:20:00Z",
  "next_charge_at": "2026-11-08T10:20:00Z",
  "cancel_at_period_end": false,
  "created_at": "2026-10-08T10:20:00Z",
  "tags": { "shop": "saas", "plan": "pro" }
}

À chaque échéance, la plateforme débite le moyen de paiement enregistré, émet une facture et vous envoie subscription.renewed et invoice.finalized.

`status`	Signification
`incomplete`	première échéance pas encore payée
`active`	à jour
`past_due`	une échéance a échoué ; les relances sont en cours
`unpaid`	relances épuisées avec `dunning.finalAction: unpaid` : l'abonnement reste, impayé
`canceled`	résilié (par vous, ou après les relances avec `finalAction: cancel`)

2. Changer de formule

Les nouvelles lignes s'appliquent à partir de la prochaine échéance (pas de prorata dans cette version) :

curl -s -X PUT https://billing-api.dev.stackngo.fr/v1/subscriptions/sub_01J9ZR2B6C7D8E9F0G1H/lines \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "lines": [ { "label": "Offre Business", "quantity": "1", "unit_amount": "99.00", "tax_category": "S", "tax_rate": "20.00" } ] }'

En attendant l'échéance, elles apparaissent dans pending_lines.

3. Résilier

curl -s -X POST https://billing-api.dev.stackngo.fr/v1/subscriptions/sub_01J9ZR2B6C7D8E9F0G1H/cancel \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "at_period_end": true }'

at_period_end: true (défaut) : l'abonnement court jusqu'à current_period_end, puis passe canceled. false : résiliation immédiate, sans remboursement automatique (voir Remboursements et avoirs si vous voulez rembourser).

4. Lister les abonnements

curl -s "https://billing-api.dev.stackngo.fr/v1/subscriptions?customer_id=cus_01J9ZR1A2B3C4D5E6F7G&status=past_due" \
  -H "Authorization: Bearer $TOKEN"

Ce que vous pouvez en attendre

Une facture par échéance, jamais deux pour la même période, même si un débit est retenté.
Les relances suivent votre compte : après un échec, nouvelles tentatives aux délais de dunning.retryDelays, abonnement en past_due pendant ce temps, puis unpaid ou canceled selon dunning.finalAction. Chaque étape vous est notifiée (subscription.past_due, subscription.unpaid, subscription.canceled).
Si la banque de votre client exige une authentification forte à une échéance, l'échéance échoue et suit les relances ; envoyez-lui un lien de portail pour qu'il mette à jour son moyen de paiement.
C'est vous qui prévenez votre client (e-mail de renouvellement, d'échec, de résiliation), à partir des webhooks.

Si ça ne marche pas

Ce que vous voyez	Cause	Correction
`422` sur `subscription`	`subscription` absent ou `interval` invalide	donner `interval` (et `interval_count` entre 1 et 36)
`403` à la création	`subscription` absent de `billingModes`, ou scope `carts` manquant	corriger le `BillingAccount`
`409` sur `PUT …/lines` ou `cancel`	abonnement déjà résilié	créer un nouvel abonnement
Abonnement resté `incomplete`	la première échéance n'a pas été payée	renvoyer un nouveau panier
Abonnement en `past_due`	échec de débit à l'échéance	lien de portail au client pour changer de moyen de paiement

Voir aussi Dépannage des paiements.

À quoi ça sert​

Prérequis​

1. Créer le panier d'abonnement​

Ce que vous obtenez​

2. Changer de formule​

3. Résilier​

4. Lister les abonnements​

Ce que vous pouvez en attendre​

Si ça ne marche pas​

Voir aussi​