API : commandes

L'API des commandes vous permet de rechercher des commandes, de récupérer une commande précise, de mettre à jour les informations d'une commande et de modifier le statut de plusieurs commandes à la fois.

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.

• Obtenir toutes les commandes
• Obtenir une commande par jeton
• Mettre à jour une commande
• Mettre à jour des commandes en lot
• Obtenir les biens numériques d'une commande

GET /orders

Récupère toutes les commandes complétées.

URL de la ressource

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

En-têtes

Nom	Valeur	Obligatoire?	Description
Accept	application/json	Oui	Doit toujours être spécifié. L'API ne prend en charge que le JSON.

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 les commandes par statut. Valeurs : InProgress, Processed, Disputed, Shipped, Delivered, Pending, Cancelled.
paymentStatus	Non	string	Filtre par statut de paiement. Valeurs : Paid, Deferred, PaidDeferred, ChargedBack, Refunded, Paidout, Failed, Pending, Expired, Cancelled, Open, Authorized.
format	Non	string	Niveau de détail des éléments de la liste. Full (par défaut) retourne les commandes complètes; Excerpt retourne des résumés allégés.
hasPendingWithdrawal	Non	bool	Filtre les commandes ayant une demande de rétractation en attente.
campaignId	Non	guid	Retourne uniquement les commandes récupérées par cette campagne de récupération de paniers abandonnés.
invoiceNumber	Non	string	Filtre par numéro de facture.
productId	Non	string	Retourne les commandes contenant ce produit. Doit être l'identifiant défini par l'utilisateur, et non l'identifiant interne de Snipcart.
placedBy	Non	string	Nom ou courriel de l'acheteur.
from	Non	datetime	Retourne les commandes passées après cette date.
to	Non	datetime	Retourne les commandes passées avant cette date.
isRecurringOrder	Non	bool	Filtre par commandes récurrentes (true/false).
includeTestOrders	Non	bool	Lorsque la requête est faite en mode Live, mettez true pour aussi retourner les commandes en mode Test.
billingAddressCity	Non	string	Correspondance exacte sur la ville de facturation.
billingAddressCountry	Non	string	Correspondance exacte, code pays à 2 lettres.
billingAddressProvince	Non	string	Correspondance exacte sur la province/l'état de facturation.
billingAddressPostalCode	Non	string	Correspondance exacte sur le code postal de facturation.
shippingAddressCity	Non	string	Correspondance exacte sur la ville de livraison.
shippingAddressCountry	Non	string	Correspondance exacte, code pays à 2 lettres.
shippingAddressProvince	Non	string	Correspondance exacte sur la province/l'état de livraison.
shippingAddressPostalCode	Non	string	Correspondance exacte sur le code postal de livraison.

Exemple de requête

curl -H "Accept: application/json" \
  "https://app.snipcart.com/api/orders?offset=0&limit=50&status=Processed" \
  -u {API_KEY}:

Exemple de réponse

{
  "totalItems": 10,
  "offset": 0,
  "limit": 50,
  "items": [
    {
      "token": "d16e2f60-39f1-4a4c-b1c3-8a2e166d3f70",
      "creationDate": "2013-10-21T20:36:26.46Z",
      "status": "Processed",
      "paymentMethod": "CreditCard",
      "invoiceNumber": "SNIP-0001",
      "email": "geeks@snipcart.com",
      ...
    }
  ]
}

GET /orders/{token}

Récupère une commande précise, incluant tous les articles, codes promotionnels et taxes appliquées.

URL de la ressource

GET https://app.snipcart.com/api/orders/{token}

En-têtes

Nom	Valeur	Obligatoire?	Description
Accept	application/json	Oui	Doit toujours être spécifié.

Paramètres de chemin

Nom	Obligatoire?	Type	Description
token	Oui	guid	Le jeton unique de la commande.

Paramètres de requête

Nom	Obligatoire?	Type	Description
includeTestOrders	Non	bool	Lorsque la requête est faite en mode Live, mettez true pour récupérer une commande en mode Test.

Exemple de requête

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

Exemple de réponse

{
  "token": "93c4604e-35ac-4db7-b3f1-2871476e9e6a",
  "status": "Processed",
  "invoiceNumber": "SNIP-1427",
  "items": [
    {
      "id": "1",
      "name": "Un poster",
      "price": 300,
      "quantity": 1,
      ...
    }
  ],
  "taxes": [
    { "taxName": "TPS", "taxRate": 0.05, "amount": 12.5 },
    { "taxName": "TVQ", "taxRate": 0.09975, "amount": 24.94 }
  ],
  ...
}

PUT /orders/{token}

Met à jour une commande précise. Utilisez ce point de terminaison pour changer le statut, définir les informations de suivi, modifier les adresses ou attacher des métadonnées. Seuls les champs que vous incluez dans le corps sont modifiés; tout le reste demeure inchangé.

⚠️ Important : Faire passer le statut d'une commande de Pending à Processed et le statut de paiement de Authorized à Paid capturera le paiement (s'applique uniquement aux paiements en deux étapes de Stripe).

URL de la ressource

PUT https://app.snipcart.com/api/orders/{token}

En-têtes

Nom	Valeur	Obligatoire?	Description
Accept	application/json	Oui	Doit toujours être spécifié.
Content-Type	application/json	Oui	JSON uniquement. Les autres types de contenu (p. ex. XML) ne sont pas pris en charge.

Paramètres de chemin

Nom	Obligatoire?	Type	Description
token	Oui	guid	Le jeton unique de la commande.

Paramètres du corps

Nom	Obligatoire?	Type	Description
status	Non	string	Nouveau statut de la commande. Valeurs : InProgress, Processed, Disputed, Shipped, Delivered, Pending, Cancelled.
paymentStatus	Non	string	Statut de paiement. Valeurs : Paid, Deferred, PaidDeferred, ChargedBack, Refunded, Paidout, Failed, Pending, Expired, Cancelled, Open, Authorized.
trackingNumber	Non	string	Numéro de suivi de la commande.
trackingUrl	Non	string	URL de suivi pour le client.
email	Non	string	Adresse courriel du client sur la commande.
billingAddress	Non	object	Adresse de facturation. Doit contenir au moins les champs minimaux requis (nom, adresse, ville, pays, code postal), sinon elle est ignorée.
shippingAddress	Non	object	Adresse de livraison. Même règle de champs minimaux requis que billingAddress.
notes	Non	string	Notes internes attachées à la commande.
customFields	Non	array	Champs personnalisés de la commande, chacun étant un objet avec name et value.
metadata	Non	object	Objet JSON arbitraire contenant des métadonnées personnalisées. Exemple : { "internal_id": "12345", "external_user_id": "user_1" }.

Exemple de requête

curl -X PUT https://app.snipcart.com/api/orders/{token} \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u {API_KEY}: \
  -d '{"status": "Shipped", "trackingNumber": "1Z999", "trackingUrl": "https://track.example.com/1Z999"}'

Exemple de réponse

{
  "token": "c7af6278-1c06-411d-b009-22a839efda75",
  "status": "Shipped",
  "invoiceNumber": "SNIP-1427",
  "trackingNumber": "1Z999",
  "trackingUrl": "https://track.example.com/1Z999",
  "items": [
    {
      "id": "1",
      "name": "Un poster",
      "price": 300,
      "quantity": 1
    }
  ],
  "taxes": [
    { "taxName": "TPS", "taxRate": 0.05, "amount": 12.5 },
    { "taxName": "TVQ", "taxRate": 0.09975, "amount": 24.94 }
  ],
  "hasPendingWithdrawal": true,
  "withdrawals": [
    {
      "id": "5b8c9d10-7e2f-4a8b-9c2d-1e3f4a5b6c7d",
      "orderToken": "c7af6278-1c06-411d-b009-22a839efda75",
      "orderInvoiceNumber": "SNIP-1427",
      "customerName": "Marie Dubois",
      "requestedAt": "2026-05-07T14:32:11Z",
      "isPartial": true,
      "isOutsideWithdrawalPeriod": false,
      "refundAmount": 300,
      "resolution": "Pending",
      "confirmationNumber": "WD-20260507-5B8C9D10",
      "items": [
        {
          "itemUniqueId": "1",
          "itemName": "Un poster",
          "quantity": 1,
          "unitPrice": 300,
          "totalPrice": 300
        }
      ]
    }
  ],
  ...
}

PATCH /orders

Met à jour le statut de plusieurs commandes à la fois. Envoyez un tableau d'objets { id, status }, où id est le jeton de la commande. Chaque changement de statut déclenche les mêmes événements et notifications qu'une mise à jour individuelle.

URL de la ressource

PATCH https://app.snipcart.com/api/orders

En-têtes

Nom	Valeur	Obligatoire?	Description
Accept	application/json	Oui	Doit toujours être spécifié.
Content-Type	application/json	Oui	JSON uniquement.

Paramètres du corps

Un tableau JSON, où chaque élément est :

Nom	Obligatoire?	Type	Description
id	Oui	guid	Le jeton de la commande à mettre à jour.
status	Oui	string	Nouveau statut. Valeurs : InProgress, Processed, Disputed, Shipped, Delivered, Pending, Cancelled.

Paramètres de requête

Nom	Obligatoire?	Type	Description
includeTestOrders	Non	bool	En mode Live, mettez true pour aussi inclure les commandes en mode Test dans le lot.

Exemple de requête

curl -X PATCH https://app.snipcart.com/api/orders \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u {API_KEY}: \
  -d '[{"id": "c7af6278-1c06-411d-b009-22a839efda75", "status": "Shipped"}, {"id": "d16e2f60-39f1-4a4c-b1c3-8a2e166d3f70", "status": "Delivered"}]'

Exemple de réponse

[
  { "id": "c7af6278-1c06-411d-b009-22a839efda75", "status": "Shipped" },
  { "id": "d16e2f60-39f1-4a4c-b1c3-8a2e166d3f70", "status": "Delivered" }
]

GET /orders/{token}/digital

Retourne la liste des biens numériques attachés à une commande.

URL de la ressource

GET https://app.snipcart.com/api/orders/{token}/digital

En-têtes

Nom	Valeur	Obligatoire?	Description
Accept	application/json	Oui	Doit toujours être spécifié.

Paramètres de chemin

Nom	Obligatoire?	Type	Description
token	Oui	guid	Le jeton unique de la commande.

Réponse

Un tableau d'objets CustomerOrderDigitalGoodDto :

Champ	Type	Description
fileGuid	string	Identifiant unique du fichier numérique.
name	string	Nom d'affichage du bien numérique.
url	string	URL de téléchargement du fichier.
downloadedNbrTime	int	Nombre de fois que l'article a été téléchargé.
maxNbrDownload	int?	Nombre maximum de téléchargements autorisés; null signifie illimité.
daysUntilExpire	int?	Nombre de jours pendant lesquels le lien de téléchargement reste valide après creationDate; null signifie qu'il n'expire pas.
creationDate	datetime	Date UTC à laquelle le bien numérique a été créé/émis.
isValid	bool	true si les deux conditions sont remplies : les téléchargements n'ont pas atteint maxNbrDownload (ou illimité), et l'article n'est pas expiré selon daysUntilExpire et creationDate.

Logique de validité (à titre de référence) :

isValid =
  (maxNbrDownload == null || downloadedNbrTime < maxNbrDownload) &&
  (daysUntilExpire == null || (nowUtc - creationDate).TotalDays <= daysUntilExpire)

Exemple de requête

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

Exemple de réponse

[
  {
    "fileGuid": "7e3f0c7a-2b4e-4db8-9b0a-0f9a8b2b8c11",
    "name": "Album – FLAC",
    "url": "https://cdn.example.com/dl/7e3f0c7a-2b4e-4db8-9b0a-0f9a8b2b8c11",
    "downloadedNbrTime": 1,
    "maxNbrDownload": 5,
    "daysUntilExpire": 30,
    "creationDate": "2025-09-01T12:34:56Z",
    "isValid": true
  },
  {
    "fileGuid": "a1b2c3d4-e5f6-47a8-9abc-def012345678",
    "name": "E-book (PDF)",
    "url": "https://cdn.example.com/dl/a1b2c3d4-e5f6-47a8-9abc-def012345678",
    "downloadedNbrTime": 3,
    "maxNbrDownload": 3,
    "daysUntilExpire": null,
    "creationDate": "2024-10-22T08:10:00Z",
    "isValid": false
  }
]