Webhooks d'événements de commande

Ces événements vous permettent de mettre à jour des systèmes qui reposent sur les informations de commande. Abonnez-vous à un événement de commande dans les paramètres de webhooks de votre tableau de bord, et Snipcart enverra le payload ci-dessous à votre endpoint chaque fois que l'événement se produit.

Enveloppe du webhook

Chaque événement de commande partage la même enveloppe de premier niveau :

Field Type Notes
eventName string L'événement qui s'est produit, p. ex. order.completed.
mode string Live ou Test.
createdOn datetime Le moment où l'événement a été émis.
content object Le payload de l'événement — voir chaque événement ci-dessous.

Certains événements ajoutent des champs de premier niveau supplémentaires à côté de content : order.status.changed et order.paymentStatus.changed ajoutent from/to, et order.trackingNumber.changed ajoute trackingNumber/trackingUrl. Ils sont listés par événement ci-dessous.

Le contenu Order

Quatre événements — order.completed, order.status.changed, order.paymentStatus.changed et order.trackingNumber.changed — livrent l'objet Order complet comme content. Ses champs les plus utilisés sont documentés ci-dessous.

Field Type Notes
token string Jeton / identifiant unique de la commande.
invoiceNumber string Numéro de facture (retombe sur le jeton).
parentToken string Pour une commande récurrente, le jeton de la commande originale.
parentInvoiceNumber string Numéro de facture de la commande parente.
email string Courriel du client.
status string InProgress, Processed, Disputed, Shipped, Delivered, Pending, Cancelled, Dispatched.
paymentStatus string Paid, Deferred, PaidDeferred, ChargedBack, Refunded, Paidout, Pending, Failed, Expired, Cancelled, Open, Authorized.
paymentMethod string Libellé d'affichage du mode de paiement.
mode string Live ou Test.
currency string Code de devise ISO (en minuscules).
lang string Langue de la commande.
creationDate datetime
modificationDate datetime
completionDate datetime Date à laquelle la commande a été complétée.
billingAddress object name, company, address1, address2, city, province, country, postalCode, phone.
shippingAddress object Même structure que billingAddress; null lorsque la commande n'est pas expédiée.
shippingAddressSameAsBilling boolean
user object Le client.
items object[] Les articles de la commande.
discounts object[] Les rabais appliqués.
taxes object[] Les taxes appliquées.
refunds object[] Les remboursements émis sur la commande.
withdrawals object[] Les demandes de rétractation UE sur la commande.
hasPendingWithdrawal boolean Vrai lorsqu'une demande de rétractation est en attente de résolution.
customFields object[] Les champs personnalisés de la commande.
metadata object Métadonnées du marchand.
shippingFees number
shippingMethod string
shippingLocalizedMethod string Nom de la méthode dans la langue du client.
shippingProvider string
trackingNumber string
trackingUrl string
cardHolderName string
creditCardLast4Digits string
cardType string
paymentDetails object Détails de paiement propres à la passerelle.
paymentGatewayUsed string
subtotal number Total des articles moins les rabais.
taxableTotal number
taxesTotal number
grandTotal number
finalGrandTotal number Total final lorsqu'ajusté.
total number finalGrandTotal lorsque défini, sinon grandTotal.
savedAmount number Montant total des rabais.
refundsAmount number Total remboursé.
adjustedAmount number Total moins les remboursements.
totalWeight number
itemsCount number Quantité totale d'articles.
summary object Sommaire de paiement (sous-total, taxes, total, …).
isRecurringOrder boolean Vrai pour une commande d'abonnement récurrente.
subscriptionId guid L'abonnement auquel cette commande appartient.
hasSubscriptions boolean
notes string
taxProvider string

Exemple complet

L'exemple montre le payload complet; le tableau ci-dessus documente les champs les plus utilisés.

{
  "eventName": "order.completed",
  "mode": "Test",
  "createdOn": "2017-10-04T19:18:53.5703196Z",
  "content": {
    "discounts": [
      {
        "amountSaved": 10,
        "discountId": "8dde2f91-4b86-4dec-b7d8-d04d26b603fb",
        "name": "10$ off",
        "combinable": true,
        "trigger": "Code",
        "code": "10_off",
        "type": "FixedAmount",
        "amount": 10,
        "id": "18069573-f782-4201-bbd0-05fd908212db",
        "creationDate": "2017-10-04T19:17:51.963Z",
        "modificationDate": "2017-10-04T19:17:51.963Z"
      }
    ],
    "items": [
      {
        "paymentSchedule": {
          "interval": "Day",
          "intervalCount": 1,
          "trialPeriodInDays": null,
          "startsOn": "2017-10-04T00:00:00Z"
        },
        "token": "1912e4c1-d008-4c15-ab12-fe21a76d30d4",
        "name": "Recurring plan",
        "price": 20,
        "quantity": 1,
        "fileGuid": null,
        "url": "/",
        "id": "PLAN",
        "initialData": "",
        "description": "",
        "categories": [],
        "weight": null,
        "image": "",
        "originalPrice": null,
        "uniqueId": "eb52e6e3-d8fa-4db4-b0a9-83c238ae1542",
        "stackable": true,
        "minQuantity": null,
        "maxQuantity": null,
        "addedOn": "2017-10-04T19:17:24Z",
        "modificationDate": "2017-10-04T19:17:26Z",
        "shippable": true,
        "taxable": true,
        "duplicatable": false,
        "width": null,
        "height": null,
        "length": null,
        "metadata": null,
        "totalPrice": 30,
        "totalWeight": 0,
        "taxes": [],
        "alternatePrices": {},
        "customFields": [
          {
            "name": "Custom",
            "displayValue": "Option 2",
            "operation": "+10.00",
            "type": "dropdown",
            "options": "Option 1|Option 2[+10.00]|Option 3[+20.00]",
            "required": false,
            "value": "Option 2",
            "optionsArray": [
              "Option 1",
              "Option 2",
              "Option 3"
            ]
          }
        ],
        "unitPrice": 30,
        "hasDimensions": false
      },
      {
        "token": "1912e4c1-d008-4c15-ab12-fe21a76d30d4",
        "name": "Bacon",
        "price": 300,
        "quantity": 1,
        "fileGuid": null,
        "url": "//localhost:3006",
        "id": "2",
        "initialData": "",
        "description": "Some bacon",
        "categories": [],
        "weight": 20,
        "image": "http://placecage.com/50/50",
        "originalPrice": null,
        "uniqueId": "9e0341a9-5d0f-498f-a4bd-1ae68c49b709",
        "stackable": true,
        "minQuantity": null,
        "maxQuantity": null,
        "addedOn": "2017-10-04T19:17:19Z",
        "modificationDate": "2017-10-04T19:17:19Z",
        "shippable": true,
        "taxable": true,
        "duplicatable": false,
        "width": null,
        "height": null,
        "length": null,
        "metadata": null,
        "totalPrice": 300,
        "totalWeight": 20,
        "taxes": [],
        "alternatePrices": {
          "vip": 700
        },
        "customFields": [
          {
            "name": "Size",
            "displayValue": "S",
            "operation": null,
            "type": "dropdown",
            "options": "S|M|L",
            "required": false,
            "value": "S",
            "optionsArray": [
              "S",
              "M",
              "L"
            ]
          },
          {
            "name": "Color",
            "displayValue": "Red",
            "operation": null,
            "type": "dropdown",
            "options": "Red|Blue|Green",
            "required": false,
            "value": "Red",
            "optionsArray": [
              "Red",
              "Blue",
              "Green"
            ]
          },
          {
            "name": "Neck",
            "displayValue": "V",
            "operation": null,
            "type": "dropdown",
            "options": "V|O|Std",
            "required": false,
            "value": "V",
            "optionsArray": [
              "V",
              "O",
              "Std"
            ]
          },
          {
            "name": "Texture",
            "displayValue": "Cotton",
            "operation": null,
            "type": "dropdown",
            "options": "Cotton|Lin|Std",
            "required": false,
            "value": "Cotton",
            "optionsArray": [
              "Cotton",
              "Lin",
              "Std"
            ]
          },
          {
            "name": "Gift",
            "displayValue": "false",
            "operation": null,
            "type": "checkbox",
            "options": "true|false",
            "required": false,
            "value": "false",
            "optionsArray": [
              "true",
              "false"
            ]
          }
        ],
        "unitPrice": 300,
        "hasDimensions": false
      }
    ],
    "refunds": [],
    "taxes": [],
    "user": {
      "id": "8de09cbc-4797-421e-841b-156954ddbb61",
      "email": "geeks@snipcart.com",
      "creationDate": "2017-09-22T14:56:05.433Z",
      "mode": "Test",
      "gravatarUrl": "https://www.gravatar.com/avatar/b2b4677d71645916cbce0a893f7f6076?s=70&d=https%3a%2f%2fcdn.snipcart.com%2fassets%2fimages%2favatar.jpg",
      "billingAddress": {
        "fullName": "Geeks Snipcart",
        "firstName": "Geeks",
        "name": "Snipcart",
        "company": "Snipcart",
        "address1": "226 rue St-Joseph E",
        "address2": "",
        "fullAddress": "226 rue St-Joseph E",
        "city": "Quebec",
        "country": "CA",
        "postalCode": "G1K3A9",
        "province": "QC",
        "phone": "888 888 8888",
        "vatNumber": null
      },
      "shippingAddress": {
        "fullName": "Geeks Snipcart",
        "firstName": "Geeks",
        "name": "Snipcart",
        "company": "Snipcart",
        "address1": "226 rue St-Joseph E",
        "address2": "",
        "fullAddress": "226 rue St-Joseph E",
        "city": "Quebec",
        "country": "CA",
        "postalCode": "G1K3A9",
        "province": "QC",
        "phone": "888 888 8888",
        "vatNumber": null
      }
    },
    "token": "1912e4c1-d008-4c15-ab12-fe21a76d30d4",
    "isRecurringOrder": false,
    "parentToken": null,
    "parentInvoiceNumber": null,
    "currency": "cad",
    "creationDate": "2017-10-03T19:47:56Z",
    "modificationDate": "2017-10-04T19:18:52Z",
    "status": "Processed",
    "paymentStatus": "Paid",
    "email": "geeks@snipcart.com",
    "billingAddress": {
      "fullName": "Geeks Snipcart",
      "firstName": "Geeks",
      "name": "Snipcart",
      "company": "Snipcart",
      "address1": "226 rue St-Joseph E",
      "address2": "",
      "fullAddress": "226 rue St-Joseph E",
      "city": "Quebec",
      "country": "CA",
      "postalCode": "G1K3A9",
      "province": "QC",
      "phone": "888 888 8888",
      "vatNumber": null
    },
    "shippingAddress": {
      "fullName": "Geeks Snipcart",
      "firstName": "Geeks",
      "name": "Snipcart",
      "company": "Snipcart",
      "address1": "226 rue St-Joseph E",
      "address2": "",
      "fullAddress": "226 rue St-Joseph E",
      "city": "Quebec",
      "country": "CA",
      "postalCode": "G1K3A9",
      "province": "QC",
      "phone": "888 888 8888",
      "vatNumber": null
    },
    "shippingAddressSameAsBilling": true,
    "creditCardLast4Digits": "4242",
    "trackingNumber": null,
    "trackingUrl": null,
    "shippingFees": 10,
    "shippingProvider": null,
    "shippingMethod": "Livraison",
    "shippingRateUserDefinedId": "free_shipping",
    "cardHolderName": "Geeks Snipcart",
    "paymentMethod": "CreditCard",
    "completionDate": "2017-10-04T19:18:30Z",
    "cardType": "Visa",
    "paymentGatewayUsed": "Test",
    "taxProvider": "Default",
    "lang": "en",
    "refundsAmount": 0,
    "adjustedAmount": 330,
    "finalGrandTotal": 330,
    "totalNumberOfItems": 0,
    "invoiceNumber": "SNIP-1003",
    "billingAddressComplete": true,
    "shippingAddressComplete": true,
    "shippingMethodComplete": true,
    "rebateAmount": 10,
    "subtotal": 320,
    "itemsTotal": 330,
    "taxableTotal": 330,
    "grandTotal": 330,
    "total": 330,
    "totalWeight": 20,
    "totalRebateRate": 0,
    "customFields": [
      {
        "name": "Slug",
        "displayValue": "Slug",
        "operation": null,
        "type": "textbox",
        "options": "",
        "required": true,
        "value": "Slug",
        "optionsArray": null
      },
      {
        "name": "Average age",
        "displayValue": "20-25",
        "operation": null,
        "type": "dropdown",
        "options": "20-25|25-30|30-35",
        "required": false,
        "value": "20-25",
        "optionsArray": [
          "20-25",
          "25-30",
          "30-35"
        ]
      },
      {
        "name": "Do you accept terms",
        "displayValue": "true",
        "operation": null,
        "type": "checkbox",
        "options": "true|false",
        "required": true,
        "value": "true",
        "optionsArray": [
          "true"
        ]
      }
    ],
    "shippingEnabled": true,
    "numberOfItemsInOrder": 2,
    "paymentTransactionId": "",
    "metadata": {},
    "taxesTotal": 0,
    "itemsCount": 2,
    "summary": {
      "subtotal": 320,
      "taxableTotal": 330,
      "total": 330,
      "payableNow": 330,
      "paymentMethod": "CreditCard",
      "taxes": [],
      "adjustedTotal": 330,
      "shipping": null
    },
    "ipAddress": "127.0.0.1",
    "hasSubscriptions": true
  }
}

Événements

order.completed

Se produit lorsqu'une nouvelle commande a été complétée avec succès. Son content est l'objet Order complet — voir Le contenu Order ci-dessus.

{
  "eventName": "order.completed",
  "mode": "Live",
  "createdOn": "2026-01-01T00:00:00Z",
  "content": { "...": "l'objet Order — voir Le contenu Order" }
}

order.status.changed

Se produit lorsque l'état d'une commande change depuis le tableau de bord ou l'API. Ajoute from/to (état de commande) au premier niveau, à côté de l'Order dans content.

{
  "eventName": "order.status.changed",
  "mode": "Live",
  "createdOn": "2026-01-01T00:00:00Z",
  "from": "InProgress",
  "to": "Processed",
  "content": { "...": "l'objet Order — voir Le contenu Order" }
}

order.paymentStatus.changed

Se produit lorsque l'état de paiement d'une commande change depuis le tableau de bord ou l'API. Ajoute from/to (état de paiement) au premier niveau, à côté de l'Order dans content.

{
  "eventName": "order.paymentStatus.changed",
  "mode": "Live",
  "createdOn": "2026-01-01T00:00:00Z",
  "from": "Authorized",
  "to": "Paid",
  "content": { "...": "l'objet Order — voir Le contenu Order" }
}

order.trackingNumber.changed

Se produit lorsque le numéro de suivi d'une commande change. Ajoute trackingNumber/trackingUrl au premier niveau, à côté de l'Order dans content.

{
  "eventName": "order.trackingNumber.changed",
  "mode": "Live",
  "createdOn": "2026-01-01T00:00:00Z",
  "trackingNumber": "123",
  "trackingUrl": "http://fedex.com",
  "content": { "...": "l'objet Order — voir Le contenu Order" }
}

order.notification.created

Se produit lorsqu'une notification est ajoutée à une commande. Le content porte la notification, pas l'Order :

  • orderToken string — le jeton de la commande.
  • notificationType string — "Invoice", "Comment", "TrackingNumber", "OrderCancelled", "Refund", "OrderShipped", "OrderReceived", "OrderPaymentExpired", "OrderStatusChanged", "RecoveryCampaign", "DigitalDownload", "Logs" et "Other".
  • sentByEmail bool — si le client a été informé par courriel.
  • sentByEmailOn DateTime — la date d'envoi du courriel, le cas échéant.
  • subject string — le sujet du courriel, le cas échéant.
  • message string — le message ou le commentaire sur la notification.
{
  "notificationType": "Comment",
  "sentByEmailOn": null,
  "sentByEmail": false,
  "orderToken": "2e8fbc93-6a20-48f1-ad39-6797a61730b5",
  "message": "<p>Backorder is expected on September 1st.</p>",
  "subject": ""
}

order.refund.created

Se produit lorsqu'une commande est entièrement ou partiellement remboursée. Le content porte le remboursement :

  • orderToken string — le jeton de la commande remboursée.
  • amount string — le montant du remboursement.
  • comment string — raison du remboursement, si spécifiée.
  • notifiedCustomerByEmail bool — si le client a été informé du remboursement par courriel.
  • currency string — la devise de la commande qui est remboursée.
{
  "orderToken": "62b31459-919e-4e6a-9c5d-764f5739cb9f",
  "amount": 29.75,
  "comment": "Requested by customer.",
  "notifiedCustomerByEmail": true,
  "currency": "CAD"
}

order.withdrawal.created

Se produit lorsqu'un client demande la rétractation de son achat. Le content porte la demande de rétractation :

  • id string (GUID) — identifiant unique de cette demande de rétractation. Utilisez-le pour faire le lien avec le withdrawalId d'un événement order.refund.created ultérieur.
  • orderToken string — jeton interne de la commande concernée par cette rétractation.
  • orderInvoiceNumber string — le numéro de facture de la commande visible par le client.
  • customerName string — le nom complet fourni par le client dans le formulaire de rétractation (la « déclaration sans équivoque » UE).
  • requestedAt string (datetime ISO 8601) — le moment où le client a soumis la demande.
  • isPartial boolean — true si le client a sélectionné des articles précis; false pour la commande complète.
  • isOutsideWithdrawalPeriod boolean — true si soumise plus de 14 jours après la complétion. Le marchand décide s'il l'honore.
  • refundAmount number — le montant total que le marchand remboursera si la demande est acceptée.
  • resolution string — l'une de Pending, Accepted, Declined. Toujours Pending à l'événement initial.
  • confirmationNumber string — identifiant lisible de la forme WD-YYYYMMDD-XXXXXXXX.
  • items array — les articles dont la rétractation est demandée (itemUniqueId, itemName, quantity, unitPrice, totalPrice). Pour une rétractation complète, tous les articles de la commande.
{
  "eventName": "order.withdrawal.created",
  "mode": "Live",
  "content": {
    "id": "5b8c9d10-7e2f-4a8b-9c2d-1e3f4a5b6c7d",
    "orderToken": "abcd1234-5678-90ef-abcd-1234567890ef",
    "orderInvoiceNumber": "SNIP-1057",
    "customerName": "Marie Dubois",
    "requestedAt": "2026-05-07T14:32:11Z",
    "isPartial": true,
    "isOutsideWithdrawalPeriod": false,
    "refundAmount": 89.97,
    "resolution": "Pending",
    "confirmationNumber": "WD-20260507-5B8C9D10",
    "items": [
      {
        "itemUniqueId": "11111111-2222-3333-4444-555555555555",
        "itemName": "Wireless headphones",
        "quantity": 1,
        "unitPrice": 89.97,
        "totalPrice": 89.97
      }
    ]
  }
}