API : abonnements

L'API des abonnements vous permet de compter, lister, consulter et annuler les abonnements d'une boutique. Elle est agnostique à la version : un seul ensemble de points de terminaison couvre à la fois les abonnements v1 (hérités) et v3, sélectionnés par requête via le paramètre version.

Les requêtes sont authentifiées avec votre clé API secrète, transmise comme nom d'utilisateur en authentification HTTP Basic avec un mot de passe vide. Avec curl : -u {API_KEY}:. Voir Authentification pour plus de détails.

Versions d'abonnement

La plupart des points de terminaison acceptent un paramètre version qui indique à l'API quel moteur d'abonnement cibler. Le champ featureVersion retourné sur les objets abonnement indique la même valeur.

Valeur Description
V1 Abonnements hérités (moteur d'abonnement v1/v2). Leur id est un GUID. Par défaut lorsque version est omis.
V3 Abonnements actuels. Leur id est le jeton de la commande initiale.

GET /subscriptions/count

Retourne le nombre d'abonnements v3 du compte authentifié se trouvant dans l'un des états donnés, limité à un mode. (Ce compteur ne considère que les abonnements v3.)

URL de la ressource

GET https://app.snipcart.com/api/subscriptions/count

Paramètres de requête

Nom Obligatoire? Type Description
states Oui string[] Un ou plusieurs états d'abonnement à compter. Répétez le paramètre pour plusieurs valeurs. Valeurs : Active, Paused, Finished, Stopped, CancellationRequested.
mode Non string Environnement à compter. Valeurs : Live, Test. Par défaut : Live.

Exemple de requête 

curl -H "Accept: application/json" \
  "https://app.snipcart.com/api/subscriptions/count?states=Active&states=Paused&mode=Live" \
  -u {API_KEY}:

Exemple de réponse 

12

GET /dashboard/subscriptions

Retourne une liste paginée des abonnements du compte (v1 + v3) pour le mode courant, du plus récent au plus ancien. Par défaut, seuls les abonnements non annulés sont retournés; utilisez status pour changer ce comportement.

URL de la ressource

GET https://app.snipcart.com/api/dashboard/subscriptions

Paramètres de requête

Nom Obligatoire? Type Description
offset Non int Nombre de résultats à ignorer. Par défaut : 0.
limit Non int Nombre de résultats à récupérer. Par défaut : 20.
status Non string Filtre par statut. Valeurs : all, active, paused, canceled. Si omis, seuls les abonnements non annulés sont retournés; une valeur non reconnue retombe sur all.
from Non datetime Retourne les abonnements créés à partir de cette date.
to Non datetime Retourne les abonnements créés jusqu'à cette date.
customerId Non string Retourne uniquement les abonnements appartenant à ce client.
userDefinedPlanName Non string Correspondance partielle sur le nom du plan.
userDefinedCustomerNameOrEmail Non string Correspondance partielle sur le courriel, le prénom ou le nom de l'abonné.
lastAttemptedInvoiceState Non string Filtre par état de la dernière facture. Valeurs : Unpaid, Declined, Paid, Void.

Réponse

Un résultat paginé. items contient les résumés d'abonnement; la réponse renvoie aussi les filtres appliqués et ajoute totalDeclinedCount (le nombre total d'abonnements du compte dont la dernière facture a été refusée). Un en-tête Link avec rel="next" est inclus pour la pagination.

Chaque élément :

Champ Type Description
id string Identifiant de l'abonnement (GUID pour v1, jeton de commande pour v3).
planName string Nom du plan.
creationDate datetime Date de création de l'abonnement.
subscriber string Courriel de l'abonné.
interval string Intervalle de facturation : daily, weekly, monthly, yearly.
intervalCount int? Nombre d'intervalles entre les prélèvements.
price decimal Montant récurrent.
totalSpent decimal Montant total facturé jusqu'à présent.
nextBillingDate datetime? Prochaine date de facturation prévue.
lastAttemptedInvoiceState string? Unpaid, Paid, Declined, Void ou Pending.
featureVersion string V1 ou V3.

Exemple de requête 

curl -H "Accept: application/json" \
  "https://app.snipcart.com/api/dashboard/subscriptions?offset=0&limit=20&status=active" \
  -u {API_KEY}:

Exemple de réponse 

{
  "totalItems": 2,
  "offset": 0,
  "limit": 20,
  "sort": [],
  "totalDeclinedCount": 1,
  "status": "active",
  "items": [
    {
      "id": "c7af6278-1c06-411d-b009-22a839efda75",
      "planName": "Café mensuel",
      "creationDate": "2026-01-15T09:24:00Z",
      "subscriber": "geeks@snipcart.com",
      "interval": "monthly",
      "intervalCount": 1,
      "price": 49.00,
      "totalSpent": 245.00,
      "nextBillingDate": "2026-02-15T09:24:00Z",
      "lastAttemptedInvoiceState": "Paid",
      "featureVersion": "V3"
    }
  ]
}

GET /dashboard/subscriptions/{id}

Récupère les détails d'un abonnement.

URL de la ressource

GET https://app.snipcart.com/api/dashboard/subscriptions/{id}

Paramètres de chemin

Nom Obligatoire? Type Description
id Oui string GUID pour un abonnement v1, jeton de commande pour un v3.

Paramètres de requête

Nom Obligatoire? Type Description
version Non string V1 (par défaut) ou V3. Voir Versions d'abonnement.

Réponses

Statut Description
200 OK Les détails de l'abonnement.
400 Bad Request version=V1 mais id n'est pas un GUID valide.
404 Not Found Abonnement introuvable, ou n'appartenant pas au compte.
409 Conflict La fonctionnalité Abonnements n'est pas activée pour cette boutique.

Objet abonnement

Champ Type Description
id string Identifiant de l'abonnement.
name string Nom de l'abonnement.
cancelledOn datetime? Date d'annulation. Omis lorsque l'abonnement n'est pas annulé.
state string État courant.
user object L'abonné : id, email, billingAddressName.
schedule object Calendrier de facturation : interval, intervalCount.
nextBillingDate string Prochaine date de facturation prévue.
gatewayId string Identifiant de la passerelle de paiement pour l'abonnement.
paymentStatus string Statut du dernier paiement.
upcomingPayments array Prélèvements à venir, chacun avec subscriptionId, name, date.
featureVersion string V1 ou V3.
amount decimal Montant récurrent.
quantity int Quantité facturée à chaque cycle.

Exemple de requête 

curl -H "Accept: application/json" \
  "https://app.snipcart.com/api/dashboard/subscriptions/{id}?version=V3" \
  -u {API_KEY}:

Exemple de réponse 

{
  "id": "c7af6278-1c06-411d-b009-22a839efda75",
  "name": "Café mensuel",
  "state": "Active",
  "user": {
    "id": "a1b2c3d4-e5f6-47a8-9abc-def012345678",
    "email": "geeks@snipcart.com",
    "billingAddressName": "Marie Dubois"
  },
  "schedule": {
    "interval": "monthly",
    "intervalCount": 1
  },
  "nextBillingDate": "2026-02-15T09:24:00Z",
  "gatewayId": "sub_1Nabc...",
  "paymentStatus": "Paid",
  "upcomingPayments": [
    {
      "subscriptionId": "c7af6278-1c06-411d-b009-22a839efda75",
      "name": "Café mensuel",
      "date": "2026-02-15T09:24:00Z"
    }
  ],
  "featureVersion": "V3",
  "amount": 49.00,
  "quantity": 1
}

DELETE /dashboard/subscriptions/{id}

Annule un abonnement.

  • Pour les abonnements v1, ceci annule l'abonnement auprès de la passerelle de paiement.
  • Pour les abonnements v3, ceci demande l'annulation : l'abonnement passe à CancellationRequested et est annulé à sa prochaine date de facturation. L'appel est idempotent — supprimer un abonnement v3 dont l'annulation a déjà été demandée retourne son état courant sans refaire la demande.

URL de la ressource

DELETE https://app.snipcart.com/api/dashboard/subscriptions/{id}

Paramètres de chemin

Nom Obligatoire? Type Description
id Oui string GUID pour un abonnement v1, jeton de commande pour un v3.

Paramètres de requête

Nom Obligatoire? Type Description
version Non string V1 (par défaut) ou V3.

Réponses

Statut Description
200 OK Les détails de l'abonnement mis à jour.
400 Bad Request version=V1 mais id n'est pas un GUID valide.
404 Not Found Abonnement introuvable, ou n'appartenant pas au compte.
409 Conflict La fonctionnalité Abonnements n'est pas activée pour cette boutique.

Exemple de requête 

curl -X DELETE "https://app.snipcart.com/api/dashboard/subscriptions/{id}?version=V3" \
  -H "Accept: application/json" \
  -u {API_KEY}:

Exemple de réponse 

{
  "id": "c7af6278-1c06-411d-b009-22a839efda75",
  "name": "Café mensuel",
  "state": "CancellationRequested",
  "nextBillingDate": "2026-02-15T09:24:00Z",
  "featureVersion": "V3",
  "amount": 49.00,
  "quantity": 1
}

GET /dashboard/subscriptions/{id}/invoices

Retourne les factures (commandes récurrentes) émises pour un abonnement.

URL de la ressource

GET https://app.snipcart.com/api/dashboard/subscriptions/{id}/invoices

Paramètres de chemin

Nom Obligatoire? Type Description
id Oui string GUID pour un abonnement v1, jeton de commande pour un v3.

Paramètres de requête

Nom Obligatoire? Type Description
version Non string V1 (par défaut) ou V3.

Pour les abonnements v3, la liste contient toujours au moins la facture initiale; un résultat vide signifie que l'abonnement est introuvable (404 Not Found).

Réponse

Un tableau d'objets facture :

Champ Type Description
id string Identifiant de la facture (le jeton de la commande).
orderToken string Jeton de la commande à l'origine de la facture.
creationDate datetime Date de complétion de la facture (commande).
modificationDate datetime Date de dernière modification de la commande.
subscriptionId string Identifiant de l'abonnement parent.
amount decimal Montant de la facture.
total decimal Identique à amount.
paid bool true lorsque le statut de paiement de la commande est payé.
number string Numéro de facture.

Exemple de requête 

curl -H "Accept: application/json" \
  "https://app.snipcart.com/api/dashboard/subscriptions/{id}/invoices?version=V3" \
  -u {API_KEY}:

Exemple de réponse 

[
  {
    "id": "c7af6278-1c06-411d-b009-22a839efda75",
    "orderToken": "c7af6278-1c06-411d-b009-22a839efda75",
    "creationDate": "2026-01-15T09:24:00Z",
    "modificationDate": "2026-01-15T09:24:05Z",
    "subscriptionId": "c7af6278-1c06-411d-b009-22a839efda75",
    "amount": 49.00,
    "total": 49.00,
    "paid": true,
    "number": "SNIP-1041"
  }
]