Products API

The Products API lets you retrieve your products, read their sales statistics, and manage inventory (stock levels and variants). Products can't be created directly through this resource — they're generated when an order is completed or when you fetch a URL (via the dashboard or the POST /products endpoint below). Define products on your own site with our HTML attributes or our JavaScript SDK.

Requests are authenticated with your secret API key, sent as the HTTP Basic username with an empty password. With curl: -u {API_KEY}:. See Authentication for details.

GET /products
GET /products/{id}
POST /products
PUT /products/{id}
DELETE /products/{id}

GET /products

Returns a paginated list of products with their sales statistics. Each item is a product excerpt.

Resource URL

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

Headers

Name	Value	Required	Description
`Accept`	`application/json`	Yes	The API only returns `application/json`.

Query Parameters

Name	Required	Type	Description
`offset`	No	`integer`	Number of items to skip. Default `0`.
`limit`	No	`integer`	Maximum number of items to return. Default `20`.
`orderBy`	No	`string`	Sort order. One of `NbrSales` (most sold first), `SalesValue` (highest total sales first) or `CreationDate` (newest first). Defaults to sorting by number of sales.
`userDefinedId`	No	`string`	Filter to products whose user-defined ID contains this value.
`keywords`	No	`string`	Filter to products whose name, description or user-defined ID contains this value.
`from`	No	`datetime`	Restrict sales statistics to orders completed on or after this date.
`to`	No	`datetime`	Restrict sales statistics to orders completed on or before this date.
`archived`	No	`boolean`	When `true`, include archived products. Default `false` (archived products are excluded).
`excludeZeroSales`	No	`boolean`	When `true`, only return products that have at least one sale. Default `false`.

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": [
    {
      "statistics": {
        "numberOfSales": 29,
        "totalSales": 608.71
      },
      "price": 20.99,
      "categories": [],
      "id": "325bfaef-d665-4c9a-a965-f5bd6ab46934",
      "userDefinedId": "HGW",
      "account_Id": 12345,
      "mode": "Test",
      "url": "/snipcart-jekyll-integration",
      "creationDate": "2016-05-25T21:21:27.213Z",
      "modificationDate": "2016-11-01T16:20:44.377Z",
      "name": "How Google Works",
      "description": "",
      "image": "https://example.com/how-google-works.jpg",
      "archived": false,
      "customFields": [],
      "metadata": {
        "votes": 95,
        "score": 336
      },
      "fileGuid": null
    },
    {
      "statistics": {
        "numberOfSales": 0,
        "totalSales": 0.0
      },
      "totalStock": 11,
      "price": 299.99,
      "categories": [],
      "id": "3932ecd1-6508-4209-a7c6-8da4cc75590d",
      "userDefinedId": "AP1",
      "account_Id": 12345,
      "mode": "Test",
      "url": "/product-examples.html",
      "creationDate": "2016-11-03T12:51:04.297Z",
      "modificationDate": "2016-11-03T12:51:28.873Z",
      "name": "Android Phone",
      "description": "",
      "image": "",
      "archived": false,
      "stock": 1,
      "allowOutOfStockPurchases": false,
      "inventoryManagementMethod": "Variant",
      "customFields": [
        {
          "name": "Size",
          "type": "dropdown",
          "options": "16GB|32GB[+50.00]|128GB[+200.00]",
          "required": false,
          "value": "128GB",
          "operation": 200.00,
          "optionsArray": [
            "16GB",
            "32GB",
            "128GB"
          ]
        }
      ],
      "variants": [
        {
          "stock": 10,
          "variation": [
            { "name": "Size", "option": "16GB" },
            { "name": "Color", "option": "Black" }
          ],
          "allowOutOfStockPurchases": true
        },
        { "...": "..." }
      ],
      "metadata": null,
      "fileGuid": null
    }
  ]
}

GET /products/{id}

Returns a single product by identifier. {id} can be either the unique ID generated by Snipcart (a GUID) or the user-defined ID you set on your buy button.

Resource URL

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

Headers

Name	Value	Required	Description
`Accept`	`application/json`	Yes	The API only returns `application/json`.

Path Parameters

Name	Required	Type	Description
`id`	Yes	`string`	The Snipcart-generated GUID, or the user-defined ID of the product.

Example request

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

Example response

{
  "totalStock": 11,
  "price": 299.99,
  "categories": [],
  "id": "3932ecd1-6508-4209-a7c6-8da4cc75590d",
  "userDefinedId": "AP1",
  "account_Id": 12345,
  "mode": "Test",
  "url": "/product-examples.html",
  "name": "Android Phone",
  "description": "",
  "image": "",
  "fileGuid": null,
  "creationDate": "2016-11-03T12:51:04.297Z",
  "modificationDate": "2016-11-03T12:51:28.873Z",
  "archived": false,
  "inventoryManagementMethod": "Variant",
  "stock": 1,
  "allowOutOfStockPurchases": false,
  "statistics": {
    "numberOfSales": 0,
    "totalSales": 0.0
  },
  "customFields": [
    {
      "name": "Size",
      "type": "dropdown",
      "options": "16GB|32GB[+50.00]|128GB[+200.00]",
      "required": false,
      "value": "128GB",
      "operation": 200.00,
      "optionsArray": [
        "16GB",
        "32GB",
        "128GB"
      ]
    }
  ],
  "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
}

POST /products

Fetches the URL passed in the body and imports the products found on the page. When fetchUrl points to a standard HTML page, Snipcart imports every button carrying the snipcart-add-item CSS class. You can also point fetchUrl at a JSON document — see the JSON Crawler for the expected shape.

The response is a JSON array of the products that were imported.

⚠️ Important: This endpoint is rate-limited. Don't call it in a tight loop.

Resource URL

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

Headers

Name	Value	Required	Description
`Accept`	`application/json`	Yes	The API only returns `application/json`.
`Content-Type`	`application/json`	Yes	The request body is JSON.

Body Parameters

Name	Required	Type	Description
`fetchUrl`	Yes	`string`	The URL where the product details will be found. If no scheme is provided, `http://` is assumed.

Example request

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

Example response

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

PUT /products/{id}

Updates a product's inventory settings. {id} can be the Snipcart-generated GUID or the user-defined ID.

Because products are defined on your own site rather than in Snipcart, only inventory-related fields can be changed here. The request body is a product object, but only inventoryManagementMethod, stock, variants and allowOutOfStockPurchases are read — every other field in the body is ignored.

⚠️ Important: Updating a product also un-archives it (archived is set to false).

Resource URL

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

Headers

Name	Value	Required	Description
`Accept`	`application/json`	Yes	The API only returns `application/json`.
`Content-Type`	`application/json`	Yes	The request body is JSON.

Path Parameters

Name	Required	Type	Description
`id`	Yes	`string`	The Snipcart-generated GUID, or the user-defined ID of the product. Passed in the URL, not the body.

Body Parameters

Name	Required	Type	Description
`inventoryManagementMethod`	No	`string`	How inventory is tracked for this product. One of `Single`, `Variant` or `Disabled`. Use `Variant` when the product has `dropdown` custom fields.
`stock`	No	`integer`	Number of items in stock. Used when `inventoryManagementMethod` is `Single`.
`variants`	No	`array`	Per-variant stock levels. Used when `inventoryManagementMethod` is `Variant`. See the variant fields below.
`allowOutOfStockPurchases`	No	`boolean`	When `true`, the product can be bought even when out of stock (stock may go negative). When `false`, out-of-stock purchases are blocked.

Each entry in variants has the following fields:

Name	Required	Type	Description
`variation`	Yes	`array`	The combination that identifies this variant, as `name`/`option` pairs matching the product's custom-field values, e.g. `[{ "name": "Size", "option": "32GB" }, { "name": "Color", "option": "Black" }]`.
`stock`	No	`integer`	Number of items of this variant in stock.
`allowOutOfStockPurchases`	No	`boolean`	When `true`, this variant can be bought even when out of stock (stock may go negative). When `false`, out-of-stock purchases are blocked.

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

{
  "totalStock": 20,
  "price": 299.99,
  "categories": [],
  "id": "3932ecd1-6508-4209-a7c6-8da4cc75590d",
  "userDefinedId": "AP1",
  "account_Id": 12345,
  "mode": "Test",
  "url": "/product-examples.html",
  "name": "Android Phone",
  "description": "",
  "image": "",
  "fileGuid": null,
  "creationDate": "2016-11-03T12:51:04.297Z",
  "modificationDate": "2016-11-03T12:51:28.873Z",
  "archived": false,
  "inventoryManagementMethod": "Single",
  "stock": 20,
  "allowOutOfStockPurchases": false,
  "statistics": {
    "numberOfSales": 0,
    "totalSales": 0.0
  },
  "metadata": null
}

DELETE /products/{id}

Archives a product. {id} can be the Snipcart-generated GUID or the user-defined ID. The archived product is returned in the response.

⚠️ Important: This does not permanently delete the product — it sets archived to true. An archived product no longer appears in the default product listing, but it is automatically restored if it is added to a cart again or re-fetched.

Resource URL

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

Headers

Name	Value	Required	Description
`Accept`	`application/json`	Yes	The API only returns `application/json`.

Path Parameters

Name	Required	Type	Description
`id`	Yes	`string`	The Snipcart-generated GUID, or the user-defined ID of the product. Passed in the URL, not the body.

Example request

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

Example response

{
  "price": 299.99,
  "categories": [],
  "id": "3932ecd1-6508-4209-a7c6-8da4cc75590d",
  "userDefinedId": "AP1",
  "account_Id": 12345,
  "mode": "Test",
  "url": "/product-examples.html",
  "name": "Android Phone",
  "description": "",
  "image": "",
  "fileGuid": null,
  "creationDate": "2016-11-03T12:51:04.297Z",
  "modificationDate": "2016-11-03T12:51:28.873Z",
  "archived": true,
  "statistics": {
    "numberOfSales": 0,
    "totalSales": 0.0
  },
  "metadata": null
}

Products API

Table of contents

GET /products

Headers

Query Parameters

Example request

Example response

GET /products/{id}

Headers

Path Parameters

Example request

Example response

POST /products

Headers

Body Parameters

Example request

Example response

PUT /products/{id}

Headers

Path Parameters

Body Parameters

Example request

Example response

DELETE /products/{id}

Headers

Path Parameters

Example request

Example response

Was this article helpful?