Products

Retrieve your products, get some statistics or keep track of your inventory. This endpoint lets you also update the inventory if needed.

Please note that you can't create products with the API. Products are created or updated whenever they're added to the cart. You will need to define products using our HTML syntax or with our JavaScript API on your site.

GET /products

This method returns a list of products.

Resource URL

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

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.

Parameters

Name Required? Type Description
limit No int The maximum number of items returned by the request. Default value is 20.
offset No int The number of items that will be skipped. Default value is 0.
userDefinedId No string The product ID defined by the user.
from No datetime Filter products to return those that have been bought from specified date.
to No datetime Filter products to return those that have been bough until specified date.

Example request

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

Example response

{
  "totalItems": 29,
  "offset": 0,
  "limit": 50,
  "items": [
    {
      "mode": "Test",
      "userDefinedId": "HGW",
      "url": "/snipcart-jekyll-integration",
      "price": 20.99,
      "name": "How Google Works",
      "description": "",
      "image": "http://d.gr-assets.com/books/1422538855l/23158207.jpg",
      "archived": false,
      "statistics": {
        "numberOfSales": 29,
        "totalSales": 608.71
      },
      "customFields": [],
      "metadata": {
        "votes": 95,
        "score": 336
      },
      "id": "325bfaef-d665-4c9a-a965-f5bd6ab46934",
      "creationDate": "2016-05-25T21:21:27.213Z",
      "modificationDate": "2016-11-01T16:20:44.377Z"
    },
     {
      "mode": "Test",
      "userDefinedId": "AP1",
      "url": "/product-examples.html",
      "price": 299.99,
      "name": "Android Phone",
      "description": "",
      "image": "",
      "archived": false,
      "inventoryManagementMethod": "Variant",
      "stock": 1,
      "totalStock": 11,
      "allowOutOfStockPurchases": false,
      "statistics": {
        "numberOfSales": 0,
        "totalSales": 0
      },
      "customFields": [
        {
          "name": "Size",
          "operation": "+200.00",
          "type": "dropdown",
          "options": "16GB|32GB[+50.00]|128GB[+200.00]",
          "required": false,
          "value": "128GB",
          "optionsArray": [
            "16GB",
            "32GB",
            "128GB"
          ]
        },
        {
          "name": "Color",
          "operation": "",
          "type": "dropdown",
          "options": "Black|Blue|Red|White",
          "required": false,
          "value": "Blue",
          "optionsArray": [
            "Black",
            "Blue",
            "Red",
            "White"
          ]
        }
      ],
      "variants": [
        {
          "stock": 10,
          "variation": [
            {
              "name": "Size",
              "option": "16GB"
            },
            {
              "name": "Color",
              "option": "Black"
            }
          ],
          "allowOutOfStockPurchases": true
        },
        {
          "stock": 1,
          "variation": [
            {
              "name": "Size",
              "option": "32GB"
            },
            {
              "name": "Color",
              "option": "Red"
            }
          ],
          "allowOutOfStockPurchases": false
        }
      ],
      "metadata": {
          "meta": true
      },
      "id": "3932ecd1-6508-4209-a7c6-8da4cc75590d",
      "creationDate": "2016-11-03T12:51:04.297Z",
      "modificationDate": "2016-11-03T12:51:28.873Z"
    }
  ]
}

GET /products/{id}

This method returns a product by its identifier. The ID can be the unique ID generated by Snipcart or the ID specified by the user.

Resource URL

GET https://app.snipcart.com/api/products/3932ecd1-6508-4209-a7c6-8da4cc75590d

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.

Parameters

Name Required? Type Description
id No string The unique ID of the product generated by Snipcart. Can also be the user defined id.

Example request

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

Example response

{
  "mode": "Test",
  "userDefinedId": "AP1",
  "url": "/product-examples.html",
  "price": 299.99,
  "name": "Android Phone",
  "description": "",
  "image": "",
  "archived": false,
  "inventoryManagementMethod": "Variant",
  "stock": 1,
  "totalStock": 11,
  "allowOutOfStockPurchases": false,
  "statistics": {
    "numberOfSales": 0,
    "totalSales": 0
  },
  "customFields": [
    {
      "name": "Size",
      "operation": "+200.00",
      "type": "dropdown",
      "options": "16GB|32GB[+50.00]|128GB[+200.00]",
      "required": false,
      "value": "128GB",
      "optionsArray": [
        "16GB",
        "32GB",
        "128GB"
      ]
    },
    {
      "name": "Color",
      "operation": "",
      "type": "dropdown",
      "options": "Black|Blue|Red|White",
      "required": false,
      "value": "Blue",
      "optionsArray": [
        "Black",
        "Blue",
        "Red",
        "White"
      ]
    }
  ],
  "variants": [
    {
      "stock": 10,
      "variation": [
        {
          "name": "Size",
          "option": "16GB"
        },
        {
          "name": "Color",
          "option": "Black"
        }
      ],
      "allowOutOfStockPurchases": true
    },
    {
      "stock": 1,
      "variation": [
        {
          "name": "Size",
          "option": "32GB"
        },
        {
          "name": "Color",
          "option": "Red"
        }
      ],
      "allowOutOfStockPurchases": false
    }
  ],
  "metadata": null,
  "id": "3932ecd1-6508-4209-a7c6-8da4cc75590d",
  "creationDate": "2016-11-03T12:51:04.297Z",
  "modificationDate": "2016-11-03T12:51:28.873Z"
}

POST /products

This method will fetch the URL passed in parameter and generate products found on the page. When the fetchUrl value is a standard HTML page, we will find all buttons on the page having the snipcart-add-item css class. Those products will then be imported into Snipcart. You can also define your products with a JSON object. You can take a look at our JSON Crawler section to understand how to define products.

In the response you can expect to receive newly imported products as a JSON array.

Resource URL

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

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.
Content-Type application/json Yes The request body needs to be JSON so we specify the content type.

Parameters

Name Required? Type Description
fetchUrl Yes string The URL where we will find product details.

Example request

curl https://app.snipcart.com/api/products
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -u {API_KEY}: \
  -d "{fetchUrl: 'https://yoursite.com/products.json'}"

Example response

[
  {
    "mode": "Test",
    "userDefinedId": "123",
    "url": "/products.json",
    "price": 10.00,
    "name": "Product 123",
    "description": null,
    "image": null,
    "archived": false,
    "statistics": {
      "numberOfSales": 0,
      "totalSales": 0
    },
    "customFields": [],
    "metadata": null,
    "id": "3e330cf2-6962-4875-8c9d-73f337b6de3e",
    "creationDate": "2016-12-13T15:54:24.5595583Z",
    "modificationDate": "2016-12-13T15:54:24.5595583Z"
  },
  {
    "mode": "Test",
    "userDefinedId": "456",
    "url": "/products.json",
    "price": 40.00,
    "name": "Product 456",
    "description": null,
    "image": null,
    "archived": false,
    "statistics": {
      "numberOfSales": 0,
      "totalSales": 0
    },
    "customFields": [],
    "metadata": null,
    "id": "c148bdb5-92ea-4c50-a7ec-46763dd1217a",
    "creationDate": "2016-12-13T15:54:24.5908458Z",
    "modificationDate": "2016-12-13T15:54:24.5908458Z"
  }
]

PUT /products/{id}

This method allows to update a specific product. The ID can be the unique ID generated by Snipcart or the ID specified by the user.

As products are not defined on our side, you can only change some attributes such as inventory values.

Resource URL

GET https://app.snipcart.com/api/products/3932ecd1-6508-4209-a7c6-8da4cc75590d

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.

Parameters

Name Required? Type Description
id No string The unique ID of the product generated by Snipcart. Can also be the user defined id. This parameter is passed through the URL and not the request body
inventoryManagementMethod No enum Specifies how inventory should be tracked for this product. Can be Single or Variant. Variant can be used when a product has some dropdown custom fields.
variants No object Allows to set stock per product variant. See variant description below.
stock No int The number of items in stock. Will be used when inventoryManagementMethod is Single.
allowOutOfStockPurchases No bool If true a customer will be able to buy the product even if it's out of stock. The stock level might be negative. If false it will be impossible to buy the product.

Variant parameters

When inventoryManagementMethod is Variant you must define a list of variants with their stock level for the product.

Name Required ? Type Description
variation yes array The specifics of the variation. Must be custom fields possible values. For example [{ "name": "Size", "value": "32GB" }, { "name": "Color", "value": "Black " }]
stock No int The number of items of this variation in stock.
allowOutOfStockPurchases No bool If true a customer will be able to buy the product variation even if it's out of stock. The stock level might be negative. If false it will be impossible to buy the product variation.

Example request

curl https://app.snipcart.com/api/products/AP1
  -X PUT \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -u {API_KEY} \
  -d "{ 'inventoryManagementMethod': 'Single', 'stock': 20 }"

Example response

{
  "mode": "Test",
  "userDefinedId": "AP1",
  "url": "/product-examples.html",
  "price": 299.99,
  "name": "Android Phone",
  "description": "",
  "image": "",
  "archived": false,
  "inventoryManagementMethod": "Single",
  "stock": 20,
  "totalStock": 20,
  "allowOutOfStockPurchases": false,
  "statistics": {
    "numberOfSales": 0,
    "totalSales": 0
  },
  "customFields": [
    {
      "name": "Size",
      "operation": "+200.00",
      "type": "dropdown",
      "options": "16GB|32GB[+50.00]|128GB[+200.00]",
      "required": false,
      "value": "128GB",
      "optionsArray": [
        "16GB",
        "32GB",
        "128GB"
      ]
    },
    {
      "name": "Color",
      "operation": "",
      "type": "dropdown",
      "options": "Black|Blue|Red|White",
      "required": false,
      "value": "Blue",
      "optionsArray": [
        "Black",
        "Blue",
        "Red",
        "White"
      ]
    }
  ],
  "metadata": null,
  "id": "3932ecd1-6508-4209-a7c6-8da4cc75590d",
  "creationDate": "2016-11-03T12:51:04.297Z",
  "modificationDate": "2016-11-03T12:51:28.873Z"
}