API : rabais

Gérez les rabais de votre boutique de façon programmatique grâce à l'API REST de Snipcart. Cette ressource vous permet de lister, récupérer, créer, mettre à jour et supprimer les rabais de votre compte — les mêmes rabais que vous pouvez configurer dans le tableau de bord, exposés afin que vous puissiez les piloter depuis vos propres systèmes.

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. L'URL de base est toujours https://app.snipcart.com/api.

⚠️ Important : Les rabais sont lus et écrits sous la forme de l'objet rabais brut. La même forme d'objet est utilisée à la fois pour les requêtes et les réponses, de sorte que tout champ documenté sur la réponse peut aussi être envoyé lors de la création ou de la mise à jour. Plusieurs champs ne s'appliquent qu'à un déclencheur (trigger) ou à un type précis (voir ci-dessous) et sont autrement ignorés ou laissés à null.

Déclencheurs et types

Un rabais comporte deux dimensions :

trigger — la condition qui active le rabais. Détermine quels champs de « déclencheur » sont obligatoires.
type — l'action que le rabais applique une fois déclenché. Détermine quels champs d'« action » sont obligatoires.

Valeurs de trigger (chaîne) : Code, Product, Total, QuantityOfAProduct, CartContainsOnlySpecifiedProducts, CartContainsSomeSpecifiedProducts, CartContainsAtLeastAllSpecifiedProducts, CartContainsOnlyProductsFromSpecifiedCategories, CartContainsSomeProductsFromSpecifiedCategories.

Valeurs de type (chaîne) : Rate, AlternatePrice, FixedAmount, Shipping, FixedAmountOnItems, GetFreeItems, RateOnItems, AmountOnSubscription, RateOnSubscription, FixedAmountOnCategory, RateOnCategory.

Quels champs s'appliquent où (imposé par la validation côté serveur) :

Déclencheur	Champ obligatoire
`Code`	`code`
`Product`	`itemId`
`Total`	(aucun champ obligatoire; utilisez `totalToReach` pour le seuil)
`QuantityOfAProduct`	`quantityOfAProduct`
`CartContainsOnlySpecifiedProducts`, `CartContainsSomeSpecifiedProducts`, `CartContainsAtLeastAllSpecifiedProducts`	`triggerProductIds`
`CartContainsOnlyProductsFromSpecifiedCategories`, `CartContainsSomeProductsFromSpecifiedCategories`	`triggerCategories`

Type	Champ(s) obligatoire(s)
`Rate`, `RateOnSubscription`	`rate`
`RateOnItems`	`rate`, `productIds`
`RateOnCategory`	`rate`, `categories`
`FixedAmount`, `AmountOnSubscription`	`amount`
`FixedAmountOnItems`	`amount`, `productIds`
`FixedAmountOnCategory`	`amount`, `categories`
`AlternatePrice`	`alternatePrice`
`Shipping`	`shippingCost`, `shippingDescription`
`GetFreeItems`	`numberOfItemsRequired`, `numberOfFreeItems`

GET /discounts

Retourne tous les rabais de votre compte (sans pagination — la liste complète est retournée sous forme de tableau JSON).

URL de la ressource

GET https://app.snipcart.com/api/discounts

En-têtes

Nom	Obligatoire?	Description
`Accept`	Oui	Doit être `application/json`.

Exemple de requête

curl -H "Accept: application/json" \
  https://app.snipcart.com/api/discounts \
  -u {API_KEY}:

Exemple de réponse

[
    {
        "id": "2223490d-84c1-480c-b713-50cb0b819313",
        "name": "10% off everything",
        "combinable": true,
        "trigger": "Code",
        "code": "SNIP10",
        "type": "Rate",
        "rate": 10.0,
        "amount": null,
        "totalToReach": null,
        "itemId": null,
        "alternatePrice": null,
        "maxNumberOfUsages": 100,
        "maxNumberOfUsagesPerCustomer": null,
        "expires": null,
        "archived": false,
        "numberOfUsages": 12,
        "numberOfUsagesUncompleted": 1,
        "shippingDescription": null,
        "shippingCost": null,
        "shippingGuaranteedDaysToDelivery": null,
        "creationDate": "2024-01-15T18:30:00Z",
        "modificationDate": "2024-01-15T18:30:00Z"
    },
    {
        "id": "19a8d615-09f5-4808-80c2-96cd32d141f3",
        "name": "Free shipping over $150",
        "combinable": true,
        "trigger": "Total",
        "code": null,
        "type": "Shipping",
        "totalToReach": 150.0,
        "rate": null,
        "amount": null,
        "shippingDescription": "Free shipping",
        "shippingCost": 0.0,
        "shippingGuaranteedDaysToDelivery": 10,
        "maxNumberOfUsages": null,
        "expires": null,
        "archived": false,
        "numberOfUsages": 0,
        "numberOfUsagesUncompleted": 0,
        "creationDate": "2024-02-01T12:00:00Z",
        "modificationDate": "2024-02-01T12:00:00Z"
    }
]

GET /discounts/{id}

Retourne un seul rabais d'après son identifiant unique. Répond avec 404 Not Found si aucun rabais portant cet identifiant n'existe sur votre compte.

URL de la ressource

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

En-têtes

Nom	Obligatoire?	Description
`Accept`	Oui	Doit être `application/json`.

Paramètres de chemin

Nom	Obligatoire?	Type	Description
`id`	Oui	`guid`	L'identifiant unique du rabais.

Exemple de requête

curl -H "Accept: application/json" \
  https://app.snipcart.com/api/discounts/2223490d-84c1-480c-b713-50cb0b819313 \
  -u {API_KEY}:

Exemple de réponse

{
    "id": "2223490d-84c1-480c-b713-50cb0b819313",
    "name": "10% off everything",
    "combinable": true,
    "trigger": "Code",
    "code": "SNIP10",
    "type": "Rate",
    "rate": 10.0,
    "amount": null,
    "totalToReach": null,
    "itemId": null,
    "alternatePrice": null,
    "maxNumberOfUsages": 100,
    "maxNumberOfUsagesPerCustomer": null,
    "expires": null,
    "archived": false,
    "numberOfUsages": 12,
    "numberOfUsagesUncompleted": 1,
    "shippingDescription": null,
    "shippingCost": null,
    "shippingGuaranteedDaysToDelivery": null,
    "creationDate": "2024-01-15T18:30:00Z",
    "modificationDate": "2024-01-15T18:30:00Z"
}

POST /discounts

Crée un nouveau rabais. Retourne 201 Created avec le rabais créé. Les champs du corps obligatoires dépendent du trigger et du type choisis (voir Déclencheurs et types); un 400 est retourné avec des erreurs de validation si un champ obligatoire pour le déclencheur ou le type sélectionné est manquant, ou si un rabais à déclencheur Code réutilise un code actif.

URL de la ressource

POST https://app.snipcart.com/api/discounts

En-têtes

Nom	Obligatoire?	Description
`Accept`	Oui	Doit être `application/json`.
`Content-Type`	Oui	Doit être `application/json`.

Paramètres du corps

Nom	Obligatoire?	Type	Description
`name`	Oui	`string`	Le nom amical du rabais.
`trigger`	Oui	`string`	Condition qui active le rabais. L'une des valeurs de déclencheur.
`type`	Oui	`string`	Action que le rabais applique. L'une des valeurs de type.
`code`	Lorsque `trigger` vaut `Code`	`string`	Le code que le client doit saisir. Doit être unique parmi les rabais actifs.
`totalToReach`	Lorsque `trigger` vaut `Total`	`decimal`	Le montant minimum de la commande qui active le rabais.
`itemId`	Lorsque `trigger` vaut `Product`	`string`	L'identifiant unique du produit (`data-item-id`).
`quantityOfAProduct`	Lorsque `trigger` vaut `QuantityOfAProduct`	`int`	Seuil de quantité pour le ou les produits ciblés.
`triggerProductIds`	Lorsque `trigger` est l'une des valeurs `CartContains*SpecifiedProducts`	`string`	Identifiants de produits séparés par des virgules qui doivent se trouver dans le panier.
`triggerCategories`	Lorsque `trigger` est l'une des valeurs `CartContains*Categories`	`string`	Noms de catégories séparés par des virgules qui doivent se trouver dans le panier.
`rate`	Lorsque `type` vaut `Rate`, `RateOnSubscription`, `RateOnItems` ou `RateOnCategory`	`decimal`	Le pourcentage déduit (p. ex. `10` pour 10 %).
`amount`	Lorsque `type` vaut `FixedAmount`, `AmountOnSubscription`, `FixedAmountOnItems` ou `FixedAmountOnCategory`	`decimal`	Le montant fixe déduit.
`productIds`	Lorsque `type` vaut `FixedAmountOnItems` ou `RateOnItems`	`string`	Identifiants de produits (`data-item-id`) séparés par des virgules auxquels le rabais s'applique.
`categories`	Lorsque `type` vaut `FixedAmountOnCategory` ou `RateOnCategory`	`string`	Tableau encodé en JSON des noms de catégories auxquels le rabais s'applique.
`alternatePrice`	Lorsque `type` vaut `AlternatePrice`	`string`	Le nom de la liste de prix alternative à utiliser.
`shippingCost`	Lorsque `type` vaut `Shipping`	`decimal`	Le coût de livraison offert au client (utilisez `0` pour la livraison gratuite).
`shippingDescription`	Lorsque `type` vaut `Shipping`	`string`	Le nom de la méthode de livraison affiché au client.
`shippingGuaranteedDaysToDelivery`	Non	`int`	Délai de livraison estimé en jours pour un rabais `Shipping`.
`numberOfItemsRequired`	Lorsque `type` vaut `GetFreeItems`	`int`	Articles requis dans le panier avant que les articles gratuits ne soient accordés.
`numberOfFreeItems`	Lorsque `type` vaut `GetFreeItems`	`int`	Nombre d'articles gratuits accordés.
`maxNumberOfUsages`	Non	`int`	Nombre total maximum d'utilisations. Si `null`, le rabais peut être utilisé indéfiniment.
`maxNumberOfUsagesPerCustomer`	Non	`int`	Nombre maximum d'utilisations par client. Doit être `≥ 0`.
`maxAmountToReach`	Non	`decimal`	Plafond sur le montant total du rabais appliqué lorsque le rabais est combinable.
`combinable`	Non	`boolean`	Indique si ce rabais peut coexister avec d'autres rabais dans le panier. Vaut `true` par défaut. Un rabais non combinable dans le panier bloque tous les autres.
`currency`	Non	`string`	Restreint le rabais à une seule devise (omis de la réponse lorsqu'il n'est pas défini).
`expires`	Non	`datetime`	Date à laquelle le rabais expire. Si `null`, il n'expire jamais. Interprété dans le fuseau horaire de votre compte.
`appliesOnAllRecurringOrders`	Non	`boolean`	Pour les types de rabais d'abonnement, indique si le rabais s'applique à toutes les commandes récurrentes ou seulement au premier paiement.

⚠️ Important : Lorsque type vaut Shipping, la création du rabais crée aussi un taux de livraison personnalisé associé à partir de shippingCost, shippingDescription et shippingGuaranteedDaysToDelivery.

Exemple de requête

curl https://app.snipcart.com/api/discounts \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u {API_KEY}: \
  -d '{
        "name": "Free shipping over $150",
        "trigger": "Total",
        "totalToReach": 150,
        "type": "Shipping",
        "shippingDescription": "Free shipping",
        "shippingCost": 0,
        "shippingGuaranteedDaysToDelivery": 10
      }'

Exemple de réponse

{
    "id": "19a8d615-09f5-4808-80c2-96cd32d141f3",
    "name": "Free shipping over $150",
    "combinable": true,
    "trigger": "Total",
    "code": null,
    "itemId": null,
    "totalToReach": 150.0,
    "type": "Shipping",
    "rate": null,
    "amount": null,
    "alternatePrice": null,
    "maxNumberOfUsages": null,
    "maxNumberOfUsagesPerCustomer": null,
    "expires": null,
    "archived": false,
    "numberOfUsages": 0,
    "numberOfUsagesUncompleted": 0,
    "shippingDescription": "Free shipping",
    "shippingCost": 0.0,
    "shippingGuaranteedDaysToDelivery": 10,
    "creationDate": "2024-02-01T12:00:00Z",
    "modificationDate": "2024-02-01T12:00:00Z"
}

PUT /discounts/{id}

Met à jour un rabais existant. Retourne 200 OK avec le rabais mis à jour, ou 404 Not Found si le rabais n'existe pas sur votre compte. Envoyez l'objet rabais complet : les mêmes champs du corps que POST s'appliquent, en plus de archived.

URL de la ressource

PUT https://app.snipcart.com/api/discounts/{id}

En-têtes

Nom	Obligatoire?	Description
`Accept`	Oui	Doit être `application/json`.
`Content-Type`	Oui	Doit être `application/json`.

Paramètres de chemin

Nom	Obligatoire?	Type	Description
`id`	Oui	`guid`	L'identifiant unique du rabais.

Paramètres du corps

Mêmes champs que POST /discounts. En plus :

Nom	Obligatoire?	Type	Description
`archived`	Non	`boolean`	Indique si le rabais est archivé. Les rabais archivés sont inactifs mais conservés pour l'historique.

Exemple de requête

curl https://app.snipcart.com/api/discounts/19a8d615-09f5-4808-80c2-96cd32d141f3 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u {API_KEY}: \
  -X PUT \
  -d '{
        "name": "Free shipping over $150",
        "trigger": "Total",
        "totalToReach": 150,
        "type": "Shipping",
        "shippingDescription": "Free shipping",
        "shippingCost": 0,
        "shippingGuaranteedDaysToDelivery": 10,
        "archived": false
      }'

Exemple de réponse

{
    "id": "19a8d615-09f5-4808-80c2-96cd32d141f3",
    "name": "Free shipping over $150",
    "combinable": true,
    "trigger": "Total",
    "code": null,
    "itemId": null,
    "totalToReach": 150.0,
    "type": "Shipping",
    "rate": null,
    "amount": null,
    "alternatePrice": null,
    "maxNumberOfUsages": null,
    "expires": null,
    "archived": false,
    "numberOfUsages": 0,
    "numberOfUsagesUncompleted": 0,
    "shippingDescription": "Free shipping",
    "shippingCost": 0.0,
    "shippingGuaranteedDaysToDelivery": 10,
    "creationDate": "2024-02-01T12:00:00Z",
    "modificationDate": "2024-02-01T13:45:00Z"
}

DELETE /discounts/{id}

Supprime un rabais existant. Retourne 204 No Content en cas de succès, ou 404 Not Found si le rabais n'existe pas sur votre compte.

⚠️ Important : Un rabais qui a déjà été utilisé dans une commande complétée ne peut pas être supprimé (numberOfUsages > 0) — la requête retourne 400 Bad Request. Archivez-le plutôt via PUT.

URL de la ressource

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

En-têtes

Nom	Obligatoire?	Description
`Accept`	Oui	Doit être `application/json`.

Paramètres de chemin

Nom	Obligatoire?	Type	Description
`id`	Oui	`guid`	L'identifiant unique du rabais.

Exemple de requête

curl https://app.snipcart.com/api/discounts/19a8d615-09f5-4808-80c2-96cd32d141f3 \
  -H "Accept: application/json" \
  -u {API_KEY}: \
  -X DELETE