API: products

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

Please note that you can't create products with the API. Products are created or updated whenever an order is completed or a URL is fetched from the Dashboard or API. You will need to define products on your site using our HTML attributes or with our JavaScript API.

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 bought until specified date.
orderBy No string Sort products to return them in the requested order. Possible values: nbrSales (return products sorted by the number of times they were sold), salesValue (return products sorted by the total sales generated by these products) and creationDate (return products sorted by creation date, newest products first).

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 fetches the URL passed in parameter and generates 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. These 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 entry 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.

Since 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", "option": "32GB" }, { "name": "Color", "option": "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"
}

DELETE /products/{id}

This method archives the product. An archived product won't be visible in the products listing anymore. However, it will be automatically restored if it's added to a cart again or manually fetched.

Resource URL

DELETE https://app.snipcart.com/api/products/{id}

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
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

Example request 

curl https://app.snipcart.com/api/products/{id}
  -X "DELETE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -u {API_KEY}:

Was this article helpful?