API : méthodes de livraison personnalisées

L'API des méthodes de livraison personnalisées vous permet de gérer les options de livraison définies manuellement d'un compte à l'aide de votre clé d'API secrète. Une méthode de livraison est une option de livraison nommée (par exemple « Standard » ou « Express ») accompagnée d'une liste de rates[] qui peuvent être échelonnés selon le poids de la commande et/ou le total de la commande, et facultativement restreints à des pays/états précis ainsi qu'aux adresses correspondant à une expression régulière de code postal. Il s'agit des mêmes méthodes de livraison que vous pouvez configurer dans le tableau de bord sous Livraison.

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 valeurs de poids des conditions de tarif sont exprimées en grammes.

⚠️ Important : La création d'une méthode de livraison active la livraison sur le compte si elle était désactivée.

Table des matières

GET /shipping_methods

Retourne toutes les méthodes de livraison personnalisées définies sur le compte pour le mode actuel (Live ou Test, déterminé par la clé secrète utilisée).

URL de la ressource

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

En-têtes

Nom Valeur Obligatoire? Description
Accept application/json Oui La réponse est en JSON.

Exemple de requête 

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

Exemple de réponse 

[
  {
    "guaranteedEstimatedDelivery": {
      "minimumDaysForDelivery": 2,
      "maximumDaysForDelivery": 5
    },
    "rates": [
      {
        "cost": 10.00,
        "weight": {
          "from": 0,
          "to": 1000
        }
      },
      {
        "cost": 18.00,
        "weight": {
          "from": 1000,
          "to": 5000
        }
      }
    ],
    "postalCodeRegex": "G1K.*",
    "countryCondition": [
      {
        "countryCode": "CA",
        "provinceCode": "QC"
      }
    ],
    "name": "Standard",
    "localizationId": "standard-shipping",
    "onOrderTotalAbove": null,
    "Id": "5f1d3b2a-9c4e-4a1b-8d6f-2e7a1c0b9d34",
    "shippingZoneId": "north-america"
  }
]

GET /shipping_methods/{id}

Retourne une seule méthode de livraison selon son GUID. Retourne 404 Not Found si aucune méthode portant cet identifiant n'appartient au compte authentifié dans le mode actuel.

URL de la ressource

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

En-têtes

Nom Valeur Obligatoire? Description
Accept application/json Oui La réponse est en JSON.

Paramètres de chemin

Nom Obligatoire? Type Description
id Oui guid L'identifiant unique de la méthode de livraison.

Exemple de requête 

curl https://app.snipcart.com/api/shipping_methods/5f1d3b2a-9c4e-4a1b-8d6f-2e7a1c0b9d34 \
  -u {API_KEY}: \
  -H "Accept: application/json"

Exemple de réponse 

{
  "guaranteedEstimatedDelivery": {
    "minimumDaysForDelivery": 2,
    "maximumDaysForDelivery": 5
  },
  "rates": [
    {
      "cost": 10.00,
      "weight": {
        "from": 0,
        "to": 1000
      }
    }
  ],
  "postalCodeRegex": "G1K.*",
  "countryCondition": [
    {
      "countryCode": "CA",
      "provinceCode": "QC"
    }
  ],
  "name": "Standard",
  "localizationId": "standard-shipping",
  "onOrderTotalAbove": null,
  "Id": "5f1d3b2a-9c4e-4a1b-8d6f-2e7a1c0b9d34",
  "shippingZoneId": "north-america"
}

POST /shipping_methods

Crée une nouvelle méthode de livraison personnalisée sur le compte. La méthode créée est retournée, y compris son Id généré.

⚠️ Important : La création d'une méthode de livraison active la livraison sur le compte si elle était désactivée auparavant.

URL de la ressource

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

En-têtes

Nom Valeur Obligatoire? Description
Accept application/json Oui La réponse est en JSON.
Content-Type application/json Oui Le corps de la requête est en JSON.

Paramètres du corps

Nom Obligatoire? Type Description
name Oui string Nom d'affichage de la méthode de livraison.
localizationId Non string Identifiant utilisé pour localiser le nom d'affichage de la méthode.
rates Oui array Un ou plusieurs paliers de tarif. Voir l'objet tarif ci-dessous.
onOrderTotalAbove Non decimal Si défini, la méthode ne s'applique que lorsque le total de la commande dépasse ce montant.
guaranteedEstimatedDelivery Non object { "minimumDaysForDelivery": int, "maximumDaysForDelivery": int }. Fenêtre de livraison estimée.
postalCodeRegex Non string Si défini, la méthode ne s'applique qu'aux adresses de livraison dont le code postal correspond à cette expression régulière.
countryCondition Non array Restreint la méthode à des pays/états précis. Chaque entrée est { "countryCode": string, "provinceCode": string }. Omettez ou laissez vide pour autoriser tous les pays. Voir objet condition de pays.
shippingZoneId Non string Identifiant facultatif regroupant cette méthode dans une zone de livraison.

Objet tarif

Chaque entrée de rates[] décrit un coût et les conditions dans lesquelles il s'applique. Lorsque plusieurs tarifs s'appliquent, le tarif correspondant le moins cher est utilisé.

Nom Obligatoire? Type Description
cost Oui decimal Le coût de livraison pour ce tarif.
weight Non object Condition de poids { "from": int, "to": int } en grammes. L'une ou l'autre des bornes peut être omise. Le tarif s'applique lorsque le poids total de la commande se situe dans la plage.
location Non object Condition de localisation par tarif { "country": string, "province": string }. (La plupart des restrictions sont mieux exprimées au niveau de la méthode via countryCondition.)

Objet condition de pays

Nom Obligatoire? Type Description
countryCode Oui string Code de pays ISO (p. ex. US, CA).
provinceCode Non string Code d'état/de province (p. ex. QC, NY).

⚠️ Important : Un champ location hérité ({ "country": ..., "province": ... }) est encore accepté au niveau supérieur du corps comme alias de countryCondition; il est obsolète et n'est conservé que pour la rétrocompatibilité. Utilisez countryCondition pour les nouvelles intégrations.

Exemple de requête 

curl https://app.snipcart.com/api/shipping_methods \
  -u {API_KEY}: \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard",
    "localizationId": "standard-shipping",
    "rates": [
      { "cost": 10.00, "weight": { "from": 0, "to": 1000 } },
      { "cost": 18.00, "weight": { "from": 1000, "to": 5000 } }
    ],
    "guaranteedEstimatedDelivery": {
      "minimumDaysForDelivery": 2,
      "maximumDaysForDelivery": 5
    },
    "postalCodeRegex": "G1K.*",
    "countryCondition": [
      { "countryCode": "CA", "provinceCode": "QC" }
    ],
    "shippingZoneId": "north-america"
  }'

Exemple de réponse 

{
  "guaranteedEstimatedDelivery": {
    "minimumDaysForDelivery": 2,
    "maximumDaysForDelivery": 5
  },
  "rates": [
    {
      "cost": 10.00,
      "weight": {
        "from": 0,
        "to": 1000
      }
    },
    {
      "cost": 18.00,
      "weight": {
        "from": 1000,
        "to": 5000
      }
    }
  ],
  "postalCodeRegex": "G1K.*",
  "countryCondition": [
    {
      "countryCode": "CA",
      "provinceCode": "QC"
    }
  ],
  "name": "Standard",
  "localizationId": "standard-shipping",
  "onOrderTotalAbove": null,
  "Id": "5f1d3b2a-9c4e-4a1b-8d6f-2e7a1c0b9d34",
  "shippingZoneId": "north-america"
}

PUT /shipping_methods/{id}

Met à jour une méthode de livraison existante. La méthode complète est remplacée par le corps fourni, alors envoyez la représentation complète (nom, tarifs, conditions, etc.). Retourne la méthode mise à jour, ou 404 Not Found si l'identifiant est introuvable.

URL de la ressource

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

En-têtes

Nom Valeur Obligatoire? Description
Accept application/json Oui La réponse est en JSON.
Content-Type application/json Oui Le corps de la requête est en JSON.

Paramètres de chemin

Nom Obligatoire? Type Description
id Oui guid L'identifiant unique de la méthode de livraison à mettre à jour.

Paramètres du corps

Même forme de corps que POST /shipping_methods : name, localizationId, rates, onOrderTotalAbove, guaranteedEstimatedDelivery, postalCodeRegex, countryCondition, shippingZoneId. (L'alias hérité location est également accepté ici.)

Exemple de requête 

curl -X PUT https://app.snipcart.com/api/shipping_methods/5f1d3b2a-9c4e-4a1b-8d6f-2e7a1c0b9d34 \
  -u {API_KEY}: \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard (updated)",
    "rates": [
      { "cost": 12.00, "weight": { "from": 0, "to": 2000 } }
    ],
    "countryCondition": [
      { "countryCode": "CA", "provinceCode": "QC" }
    ]
  }'

Exemple de réponse 

{
  "guaranteedEstimatedDelivery": {
    "minimumDaysForDelivery": null,
    "maximumDaysForDelivery": null
  },
  "rates": [
    {
      "cost": 12.00,
      "weight": {
        "from": 0,
        "to": 2000
      }
    }
  ],
  "countryCondition": [
    {
      "countryCode": "CA",
      "provinceCode": "QC"
    }
  ],
  "name": "Standard (updated)",
  "localizationId": null,
  "onOrderTotalAbove": null,
  "Id": "5f1d3b2a-9c4e-4a1b-8d6f-2e7a1c0b9d34"
}

DELETE /shipping_methods/{id}

Supprime définitivement une méthode de livraison selon son GUID. Retourne une réponse vide 204 No Content en cas de succès, ou 404 Not Found si l'identifiant est introuvable.

URL de la ressource

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

En-têtes

Nom Valeur Obligatoire? Description
Accept application/json Oui La réponse est en JSON.

Paramètres de chemin

Nom Obligatoire? Type Description
id Oui guid L'identifiant unique de la méthode de livraison à supprimer.

Exemple de requête 

curl -X DELETE https://app.snipcart.com/api/shipping_methods/5f1d3b2a-9c4e-4a1b-8d6f-2e7a1c0b9d34 \
  -u {API_KEY}: \
  -H "Accept: application/json"