Gérer l'abonnement

Les endpoints de facturation couvrent tout le cycle de vie de l'abonnement, avec une règle : l'API prépare, la personne confirme, le prestataire de paiement exécute. Aucun argent ne transite par l'API. Toute action qui implique un paiement renvoie un lien vers la page du prestataire lui-même (Stripe Checkout, le portail client Stripe ou PayPal) où la personne voit le montant exact et confirme.

Votre clé a besoin de billing:read pour lire et de billing:manage pour créer des liens. Ces endpoints continuent de fonctionner quand la boutique n'est plus sur un forfait avec API. C'est ainsi qu'une boutique rétrogradée ou expirée revient.

1. Lire ce qui est possible

curl https://api.nembol.com/rest/v1/billing \
  -H "Authorization: Bearer $NEMBOL_API_KEY"

{
  "object": "billing",
  "billing_source": "stripe",
  "managed_elsewhere": null,
  "plan": { "key": "enterprise", "name": "Enterprise", "interval": "month" },
  "status": "active",
  "current_period_end": "2026-11-08T07:41:43.000Z",
  "cancel_at_period_end": false,
  "payment_method": { "brand": "visa", "last4": "4242" },
  "usage": { "products": 350, "max_accounts_on_one_channel": 3, "team_members": 0 },
  "plans": [
    {
      "key": "pro",
      "name": "Pro",
      "limits": { "products": 2000, "accounts_per_channel": 2, "team_members": 0 },
      "prices": {
        "month": { "amount": 49, "currency": "usd", "selectable": false,
                   "reason": "The store has 3 accounts on one channel; Pro allows 2 per channel." },
        "year":  { "amount": 441, "currency": "usd", "selectable": false, "reason": "…" }
      }
    }
    // … basic, enterprise, enterprise_plus
  ],
  "invoices": [ { "amount": "79.00", "status": "paid", "url": "https://invoice.stripe.com/…", "created_at": "…" } ],
  "actions": { "change_plan": true, "update_payment_method": true, "cancel": true, "manage": true }
}

plans[].prices.*.selectable vous indique quels changements de forfait sont acceptés en ce moment, et reason pourquoi certains ne le sont pas. Montrez-le à la personne : il est rédigé pour elle.

2. Changer de forfait

Souscrire, réactiver, passer à un forfait supérieur ou inférieur, et basculer entre mensuel et annuel passent tous par le même appel :

curl -X POST https://api.nembol.com/rest/v1/billing/plan_change_link \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan": "enterprise_plus", "interval": "year",
       "return_url": "https://app.example.com/billing/done"}'

{
  "object": "billing_link",
  "action": "change_plan",
  "provider": "stripe",
  "plan": "enterprise_plus",
  "interval": "year",
  "url": "https://billing.stripe.com/p/session/…"
}

La page qui s'ouvre dépend de la boutique :

Rien ne change tant que la personne n'a pas confirmé. Ensuite, GET /billing affiche le nouveau forfait.

Les limites sont les mêmes que dans le tableau de bord

Un changement de forfait est refusé, avant la création de tout lien, quand l'utilisation de la boutique ne tient pas dans le forfait cible :

{
  "error": {
    "type": "invalid_request_error",
    "code": "plan_limits_exceeded",
    "message": "The store has 3 accounts on one channel; Pro allows 2 per channel. Reduce usage first, or pick a larger plan.",
    "param": "plan"
  }
}

Les vérifications portent sur les produits, les comptes connectés par canal et les membres de l'équipe. Pour passer à un forfait inférieur, réduisez d'abord l'utilisation (par exemple, déconnectez un compte de canal avec POST /channel_accounts/{id}/disconnect), puis redemandez.

3. Carte, résiliation, renouvellement

Un essai n'a rien à résilier : cancel_link répond nothing_to_cancel. Un nouvel essai n'est disponible que pour les boutiques résiliées qui n'en ont jamais relancé et n'ont jamais payé, ou dont la dernière période payée s'est terminée il y a plus de 3 mois (trial_not_available sinon).

URL de retour

return_url est facultatif (par défaut, le tableau de bord Nembol). Si vous en passez une, elle doit commencer par une URL enregistrée pour la boutique. C'est la même liste d'autorisation que pour les connexions de canaux (POST /redirect_urls, ou Paramètres → Développeurs → URL de redirection).

Bonnes pratiques pour les agents

• Créez un lien juste avant de le remettre à la personne, et ne le stockez pas : les liens ont une courte durée de vie.
• Dites toujours ce qui va se passer avant d'envoyer le lien (« cela vous fait passer à Enterprise+ annuel, 1 161 $/an ; Stripe affichera le montant au prorata »).
• Vérifiez GET /billing au retour de la personne au lieu de supposer que le changement a eu lieu. Elle a peut-être fermé la page.

Dernière mise à jour le 20 octobre 2026