Needed details on shipping webhook missing in documentation

I need to be able to set the shipping rate to a specific ID or token so I can see what the value is for the order.completed webhook.

What I see is you can set a description, cost, and guaranteed days to delivery. Can I get the full spec for the key-value members for the shipping rates and/or get some clarity on how to identify what rate was selected at checkout when the order is submitted? I’d rather not do hacky string parsing on the description, but if I must I will. Using IDs or UUIDs set as the metadata or similar would allow me to more easily automate the fulfillment of the orders.

Here: Webhooks: shipping – Snipcart Documentation

Hey @debyltech ,

You can include a UserDefinedId property in the rates returned under the shipping webhook. This ID will then be included in the ShippingRateUserDefinedId field of the order.completed payload.

We’ll make sure to update our doc soon to reflect this as I’m sure you are not the only one facing this!

1 Like

What is the JSON key for this property exactly, it seems that maybe userDefinedId isn’t quite correct here when returned as the rates?

Hey @debyltech ,
It should be userDefinedId, we just saw that there is an issue with our webhooks shipping documentation, it is showing the outdated v1/v2 documentation instead of v3. I’m pasting the v3 corrected one below and looking into fixing the issue :

Webhooks: shipping

You can use the shipping rates webhook when you want to handle shipping rates calculation by yourself. Snipcart will call your application at the URL specified in your dashboard.

In your dashboard go to Store configurations → Shipping → Webhooks and enter the required endpoint information.

Snipcart will make an HTTP POST request to the URL specified. The request body will contain all the current order details.





  "eventName": "shippingrates.fetch",
  "mode": "Live",
  "createdOn": "2015-02-21T14:58:02.6738454Z",
  "content": {
    "token": "22808196-0eff-4a6e-b136-3e4d628b3cf5",
    "creationDate": "2015-02-21T14:58:02.6738454Z",
    "modificationDate": "2015-02-21T14:58:02.6738454Z",
    "status": "Processed",
    "currency": "USD",
    "lang": "en",
    "paymentMethod": "CreditCard",
    "email": "",
    "cardHolderName": "Nicolas Cage",
    "billingAddressName": "Nicolas Cage",
    "billingAddressCompanyName": "Company name",
    "billingAddressAddress1": "888 The street",
    "billingAddressAddress2": "",
    "billingAddressCity": "Québec",
    "billingAddressCountry": "CA",
    "billingAddressProvince": "QC",
    "billingAddressPostalCode": "G1G 1G1",
    "billingAddressPhone": "(888) 888-8888",
    "shippingAddressName": "Nicolas Cage",
    "shippingAddressCompanyName": "Company name",
    "shippingAddressAddress1": "888 The street",
    "shippingAddressAddress2": "",
    "shippingAddressCity": "Québec",
    "shippingAddressCountry": "CA",
    "shippingAddressProvince": "QC",
    "shippingAddressPostalCode": "G1G 1G1",
    "shippingAddressPhone": "(888) 888-8888",
    "shippingAddressSameAsBilling": true,
    "finalGrandTotal": 310.00,
    "shippingAddressComplete": true,
    "creditCardLast4Digits": "4242",
    "shippingFees": 10.00,
    "shippingMethod": "Livraison",
    "items": [{
      "uniqueId": "eb4c9dae-e725-4dad-b7ae-a5e48097c831",
      "token": "22808196-0eff-4a6e-b136-3e4d628b3cf5",
      "id": "1",
      "name": "Movie",
      "price": 300.00,
      "originalPrice": 300.00,
      "quantity": 1,
      "url": "",
      "weight": 10.00,
      "description": "Something",
      "image": "",
      "customFieldsJson": "[]",
      "stackable": true,
      "maxQuantity": null,
      "totalPrice": 300.0000,
      "totalWeight": 10.00,
      "shippable": true,
    "subtotal": 610.0000,
    "totalWeight": 20.00,
    "discounts": [],
    "willBePaidLater": false


Snipcart expects to receive a JSON object containing an array of shipping rates.


Response status code must be 2XX to indicate that the request has been handled successfully.

Required HTTP headers

Key Value
Content-Type application/json


Name Type Description Required
cost decimal Shipping method’s price. true
description string Name or description of the shipping method. true
guaranteedDaysToDelivery int Estimated time for delivery in days. false
userDefinedId string Internal ID of shipping method, can be useful when using shipping fulfillment solutions. false

Response example

	"rates": [{
	    "cost": 10,
	    "description": "10$ shipping",
	    "userDefinedId": "shipping_10",
    }, {
	    "cost": 20,
	    "description": "20$ shipping",
	    "guaranteedDaysToDelivery": 5,
        "userDefinedId": "shipping_20",
	    "cost": 30,
	    "description": "30$ shipping",
	    "userDefinedId": "shipping_30"

Quick word on the userDefinedId property, it can be especially useful when your Shipping webhook integrates with a fulfillment solution, sometimes you need to carry the unique shipping rate ID through the whole ordering process. When your rates contain this field, the property shippingRateUserDefineId property will be set on the Order, therefore available in Webhook requests and API calls.


If you want Snipcart to show an error message to your customers, you can do so by returning us a 2XX status code with the following JSON object.

  "errors": [{
    "key": "invalid_postal_code",
    "message": "The postal code is invalid."
1 Like

Awesome thank you so much, it works!