Utiliser l'API

L'API permet à vos propres systèmes de lire et de modifier des abonnements sans que personne n'ouvre l'application, et vous prévient chaque fois qu'un abonnement change, pour que vous n'ayez pas à le demander sans cesse.

Elle est utile si vous gérez une vitrine headless, si vous synchronisez les abonnements avec un ERP ou un système d'entrepôt, ou si vous voulez un message dans Slack quand quelqu'un résilie.

Tant que l'API est nouvelle, nous l'activons boutique par boutique. Si Paramètres > Intégrations > API indique « Contactez l'assistance pour faire activer l'API sur cette boutique », écrivez-nous par chat et nous l'activerons pour la vôtre.

Obtenir un jeton

Allez dans Supr Bundles & Subscriptions > Paramètres > Intégrations > API. Dans la carte Jetons API :

Donnez au jeton un Nom qui décrit ce qui va l'utiliser, pour pouvoir retrouver l'origine d'un jeton divulgué, et choisissez ce qu'il peut faire :

• Lire les abonnements, pour un système qui ne fait que des rapports.
• Modifier les abonnements, pour un système qui suspend, résilie ou reprogramme.
• Lire les points de terminaison webhook et Gérer les points de terminaison webhook, pour configurer les notifications d'événements depuis votre propre code plutôt que depuis cette page.

Cliquez ensuite sur Créer un jeton.

Donnez à chaque système son propre jeton, pour pouvoir en désactiver un sans toucher aux autres.

Le jeton n'est affiché qu'une seule fois. Copiez-le immédiatement. Nous ne le conservons pas : si vous le perdez, vous devrez en créer un nouveau. Révoquer bloque immédiatement tout ce qui utilise ce jeton.

Appeler l'API

Envoyez le jeton comme jeton bearer :

curl https://subscriptions.super-simple.co/api/v1/subscriptions \
  -H "Authorization: Bearer sss_live_..."

Vous pouvez lister les abonnements, en récupérer un, puis suspendre, reprendre, résilier, passer une commande ou annuler ce passage, modifier la prochaine date de facturation ou la formule, et ajouter, modifier ou retirer ses produits. Chaque modification renvoie l'abonnement dans son nouvel état, vous n'avez donc jamais besoin de le redemander juste après.

L'API est destinée à être appelée par vos propres serveurs. Ne placez jamais un jeton dans un navigateur, une application mobile ou tout autre endroit visible par un client, car quiconque le trouve peut modifier vos abonnements.

Réessayer en toute sécurité

Si un appel expire, vous ne pouvez pas savoir s'il a été exécuté. Envoyez un en-tête Idempotency-Key avec une valeur de votre choix sur tout appel qui modifie un abonnement : si vous réessayez avec la même clé, nous renvoyons la première réponse au lieu d'exécuter l'action deux fois :

curl -X POST https://subscriptions.super-simple.co/api/v1/subscriptions/123/pause \
  -H "Authorization: Bearer sss_live_..." \
  -H "Idempotency-Key: 9f1c2a7e-4b0d-4f2a-9c3e-8a1b2c3d4e5f"

Les clés sont valables une journée. Réutiliser une clé avec une requête différente est refusé plutôt que traité, vous ne pouvez donc pas recevoir la mauvaise réponse par erreur.

Combien d'appels vous pouvez faire

Chaque boutique démarre avec le quota standard, indiqué dans la liste Limite de débit lorsque vous créez un jeton. Si votre intégration a besoin de plus, demandez-le-nous et nous l'augmenterons : les options supérieures apparaîtront alors dans cette liste.

Chaque réponse contient X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. En cas de dépassement, vous recevez un 429 avec un Retry-After qui indique combien de secondes attendre.

Il existe aussi une limite pour l'ensemble des jetons de votre boutique, car chaque appel consomme aussi le quota Shopify de votre boutique. Si une intégration se dérègle, c'est cette limite qui l'empêche de ralentir votre admin et votre boutique.

Notifications d'événements

Plutôt que de nous demander les changements, laissez-nous vous les signaler. Dans Supr Bundles & Subscriptions > Paramètres > Intégrations > API, dans la carte Notifications d'événements, saisissez une URL, cochez les événements souhaités et cliquez sur Ajouter un point de terminaison. Nous envoyons une requête POST à cette URL chaque fois que l'un d'eux se produit, et le corps contient l'abonnement exactement tel que l'API le renverrait.

Les événements disponibles comprennent un abonnement créé, suspendu, repris, résilié, renouvelé ou en échec, un changement de sa prochaine date de facturation, une commande passée ou dont le passage est annulé, un changement de ses produits ou de sa formule, et la mise à jour de son moyen de paiement ou de son adresse d'expédition.

Votre URL doit utiliser https et être accessible depuis internet.

Vérifier qu'une notification vient bien de nous

Quand vous ajoutez un point de terminaison, nous vous montrons un secret de signature, une seule fois. Chaque envoi contient ces en-têtes :

X-SSS-Topic: subscription.paused
X-SSS-Shop-Domain: your-store.myshopify.com
X-SSS-Timestamp: 1758300000
X-SSS-Hmac-SHA256: <signature>

La signature est le HMAC SHA256 en base64 de l'horodatage, d'un point et du corps exact que nous avons envoyé, calculé avec votre secret. Vérifiez-la avant de faire confiance à quoi que ce soit :

const crypto = require("crypto");

const expected = crypto
  .createHmac("sha256", YOUR_SECRET)
  .update(`${req.headers["x-sss-timestamp"]}.${rawBody}`)
  .digest("base64");

const ok = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.headers["x-sss-hmac-sha256"])
);

YOUR_SECRET est la chaîne complète que nous vous avons montrée, qui commence par sss_whsec_. Utilisez-la telle quelle, préfixe compris.

Utilisez le corps brut exactement tel qu'il est arrivé, et non une version réencodée du JSON analysé, sinon la signature ne correspondra pas.

Rejetez aussi tout envoi dont l'horodatage date de plus de cinq minutes. L'horodatage fait partie de ce qui est signé : c'est ce qui empêche quelqu'un de rejouer un envoi qu'il aurait intercepté plus tôt.

Vous pouvez changer le secret d'un point de terminaison à tout moment avec Nouveau secret sur la même page. Cela ne modifie que ce point de terminaison. Désactiver suspend les envois vers un point de terminaison et Supprimer le supprime.

Quand votre point de terminaison est indisponible

Un envoi qui échoue est retenté à intervalles croissants pendant environ une journée avant que nous y renoncions. Si un point de terminaison refuse 20 fois de suite, nous le désactivons et vous en indiquons la raison, pour qu'une URL que vous n'utilisez plus ne soit pas retentée indéfiniment. Cliquer sur Activer lève ce blocage.

Obtenir de l'aide

Si quelque chose ne fonctionne pas, chaque réponse contient un X-Request-Id. Communiquez-le au support et nous pourrons retrouver cet appel précis.

Questions fréquentes

• Existe-t-il une API pour les abonnements ?

Oui, celle-ci. Elle est activée boutique par boutique tant qu'elle est nouvelle, contactez donc le support pour l'activer.

• Ai-je besoin de l'API pour modifier de nombreux abonnements à la fois, par exemple pour déplacer leurs dates de renouvellement ?

Pas pour une modification ponctuelle. Dans Abonnements, filtrez la liste, cochez les abonnements et utilisez l'action groupée Reprogrammer. L'API sert aux modifications que vos propres systèmes effectuent régulièrement.

• Une autre application (par exemple une application d'affiliation ou un ERP) peut-elle lire les données d'abonnement ?

Shopify ne permet qu'à l'application qui a créé un abonnement de le lire, les autres applications ne peuvent donc pas voir directement nos abonnements. Connectez votre système à cette API, ou faites lire à l'autre application les balises de commande et de client que l'application peut ajouter, consultez Paramètres des balises.

• J'ai perdu mon jeton.

Nous ne pouvons pas l'afficher à nouveau. Révoquez l'ancien et créez un nouveau jeton.

• Puis-je placer le jeton dans le thème de ma boutique ou dans une application mobile ?

Non. Quiconque peut le voir pourrait modifier vos abonnements. Appelez l'API uniquement depuis votre propre serveur.

Mis à jour le : 24/10/2026