Order validation

Creating Snipcart products boils down to adding a button to your site and defining it with data attributes.

You may wonder:

"What if I change product information with my browser developer tools? I'll be able to tamper with the price and place fraudulent orders."

Our order validation process is how we guarantee order integrity through the whole checkout.

Crawler headers

Our crawler will send three headers that can help you identify that requests are coming from Snipcart servers:

User-Agent: Snipcart/1.0
X-Snipcart-Purpose: Crawling
X-Snipcart-RequestToken: {token}

The X-Snipcart-RequestToken header will be a random token generated by our servers, you can validate it against our API by following these instructions.

Product data-item-url attribute

When configuring a product, there's a required attribute called data-item-url.

Before completing an order, Snipcart makes an HTTP request to the value specified in this attribute. We make sure the price and other important information have not been altered via browser developer tools.

You can read more about this in the security entry.

The specified URL must be the one where the Snipcart buy button for the product is available.

Important notice: For users with a single-page website, the data-item-url field should only be filled with your root domain name, such as www.example.com, or with a simple slash bar /.

Allowed domains

Before you start selling, you need to allow domains and sub-domains where Snipcart can crawl your products. In your dashboard, under Store configurations → Domains & URLs, you can set your default domain name as well as the additional allowed domains and sub-domains.

For instance, if the data-item-url value is http://test.mysite.com/products/1 and your default domain is mysite.com, our validation will fail. You need to add test.mysite.com in the allowed sub-domains for it to work.

If you want, you can also use a relative URL (/products/1). But we only validate the product in your default domain name. So, in the example above, if the data-item-url value was /products/1, we would make the HTTP request to validate the information to http://mysite.com/products/1.

To specify a relative URL, the data-item-url value must start with a /.

JSON crawler

When Snipcart validates an order's integrity, it uses the value specified in each product's data-item-url attribute.

Most times, the value specified for this attribute will be the unique URL where you're selling the item. However, merchant sites can sometimes require more complex validation scenarios.

If that's your case, there's an alternative to our default HTML crawler: our JSON crawler.

When Snipcart makes the request to the URL, if your response Content-Type header is application/json, we'll use our JSON validator instead of the HTML one.

You must return us a JSON having the following properties.

{
  "id": "20",
  "price": 50.00,
  "customFields": [],
  "url": "https://snipcart.com/products/1.json"
}

The id, price and url fields are mandatory, and they must be the same ones you specified in the product definition in your HTML. customFields is mandatory but only need to include the fields which are required or change the pricing.

{
  "id": "20",
  "price": 50.00,
  "customFields": [
    {
      "name": "Frame color",
      "options": "Black|Brown[+100.00]|Gold[+300.00]"
    },
    {
      "name": "Note",
      "required": true
    }
  ],
  "url": "/"
}

If you are using our multi-currency feature, the price property can be a hash with multiple currencies.

{
  "id": "20",
  "price": {
    "usd": "30",
    "cad": "35"
  },
  "url": "/"
}

If you intend to provide any specific measurements for your product, it is essential to include the dimensions property as well.

{
  "id": "20",
  "price": 50.00,
  "dimensions": {
    "weight": 300,
    "width": 20,
    "height": 10,
    "length": 30
  },
  "url": "/"
}

You can also return an array containing multiple objects as defined above.

[
  {
    "id": "20",
    "price": 50.00,
    "url": "https://snipcart.com/products.json"
  },
  {
    "id": "21",
    "price": 100.00,
    "url": "https://snipcart.com/products.json"
  }
]

This can be useful when your website is API-driven, using a single page application framework such as React or Vue.

Fetching products from a JSON document

From our dashboard, you can fetch products if you need to set inventory stock, for instance. If you are using our JSON validator you can also use your JSON documents to fetch products.

The document can be a JSON file containing all of your products in an array or a product individually.

The following example is a single product that can be fetched. Please note that this example also sets default stock levels.

{
  "id": "JSON_PRODUCT",
  "name":  "JSON Product",
  "url": "/products.json",
  "price": 20.00,
  "image": "http://placehold.it/300x300",
  "inventoryManagementMethod":  "Variant",
  "dimensions": {
    "weight": 300,
    "width": 20,
    "height": 10,
    "length": 30
  },
  "variants": [
    {
      "variation": [
        {
          "name": "Color",
          "option": "Red"
        },
        {
          "name": "Size",
          "option": "Small"
        }
      ],
      "stock": 10,
      "allowOutOfStockPurchases":  true
    }
  ],
  "categories": ["category1", "category2"],
  "customFields": [
    {
      "name": "Size",
      "options": "Small|Medium|Large",
      "type": "dropdown"
    },
    {
      "name": "Color",
      "options": "Red|Blue|Green",
      "type": "dropdown"
    }
  ]
}

Validating the request

Please refer to this entry to learn how to secure any endpoints that handle requests from Snipcart.