Products Resource
URL Endpoints
| Endpoint | Supported Metods | Description |
|---|---|---|
| /[store-handle]/api/v2/sales/products.json | GET | Collection of products. |
| /[store-handle]/api/v2/sales/products/[product-uuid or product-slug].json | GET, PUT, DELETE | A single product. |
| /[store-handle]/api/v2/sales/products/count.json | GET | Total result counter for a query. Returns as integer. |
URL Parameters
| Parameter | Type | Example | Description |
|---|---|---|---|
| size | integer | /[store-handle]/api/v2/webstore/products.json?size=40 | Results per page. Limited to 20, 40 or 80. Default is 40. |
| page | integer | /[store-handle]/api/v2/webstore/products.json?page=5 | Result page for query. Starts at and defaults to 0. |
| tags | string | /[store-handle]/api/v2/webstore/products.json?tags=men,bikes | Filter by tags. Multiple tags allowed. |
| query | string | /[store-handle]/api/v2/webstore/products.json?query=test | Fulltext search by query. |
| since | timestamp | /[store-handle]/api/v2/webstore/products.json?since=1253783215 | Results newer then revision. |
| sort | string | /[store-handle]/api/v2/webstore/products.json?sort=sku | Sort order for results, can be "sku", "name", "price", "value". Default is "name". |
Although you can only page through the results by at most 80 items at a time, you can get the total count of items for the given query by sending the exact same GET parameters to /[store-handle]/api/v2/webstore/products/count.json. For example /[store-handle]/api/v2/webstore/products/count.json will return the total count for all products, and /[store-handle]/api/v2/webstore/products/count.json?tags=bike will return the count for all products with tag bike. Counting does not work in combination with revision and query parameters.
Data Structure
Products describe items in your webstore including names, pricing description etc.
GET
/[store-handle]/api/v2/sales/products.json
/static/support/documentation/examples/products.json
| Name | Path | Type | Description | Example |
|---|---|---|---|---|
| type | type | string (readonly) | Resource type. Must match the resource type used in the endpoint. | "orders", "products", "customers" |
| uuid | uuid | uuid | Resource identifier. Must be a valid hex representation. | "06429e75a8ea11de80c09314b8ee4e52" |
| revision | revision | timestamp (readonly) | Resource version. Uses the timestamp format, precision up to seconds. | 1253783394 |
| date | date | timestamp (readonly) | Date created. | 1253783215 |
| sku | sku | limited string | Stock keeping unit. Should be unique across products, including variations. | "IPOD40", "SHIRT-SMALL-RED" |
| name | name | string | Product name. | "iPod 40GB", "Pretty T-Shirt" |
| slug | slug | string (readonly) | Product slug. Generated from product name. Lowercase url friendly characters only. Unique across all products. | "ipod-40gb", "pretty-t-shirt" |
| brand | brand | string | Product brand name. | "Apple", "Gucci" |
| description | description | string | Product description. | "This product is beautiful." |
| tags | tags | array with strings | Tags for this product. Values are limited lowercase strings with url friendly characters. | "men", "bike", "discounted" |
| price | price | decimal | Product price per unit. | "20.00" |
| displayPrice | displayPrice | decimal (readonly) | Product price for display purposes. Generated based on the price and store settings. Can be including or excluding tax. | "20.00" |
| tax | tax | decimal (readonly) | Calculated tax for this product. | "3.00" |
| total | total | decimal (readonly) | Calculated total for this product (price + tax). | "20.00" |
| value | value | decimal | The products stock value. This is not the actual stock value, but a custom average used for bookkeeping or margin calculations. | "18.00" |
| unit | unit | string | Unit the quantity is expressed in. | "Pieces", "Boxes", "Bottles" |
| weight | weight | decimal | Product weight. | "5.00" |
| weightUnit | weightUnit | enum | Unit the weight is expressed in. For all weight units see constants. | "KG", "LBS" |
| currency | currency | enum | Currency the price is expressed in. For all weight units see constants. | "USD", "EUR", "GBP" |
| hasStock | hasStock | bool | Whether the product has physical stock. | true, false |
| needsSerial | needsSerial | bool | Whether the product needs a serial number. | true, false |
| isTaxable | isTaxable | bool | Whether this product is taxable. | true, false |
| taxes | taxes | list with tax resources | Taxes that are applicable to this product. See the taxes resource documentation for structure. | |
| images | images | list with dictionaries | Images for this product. | |
| order | images.[index].order | integer | Order index for this image. Used to define order of product images. Should be unique across product images. | 1, 2, 3, 4 |
| description | images.[index].description | string | Image description. | "Beautiful sweater" |
| url | images.[index].url | string | Image location. Can be a full url, image uuid with format to look up in the images resource. | "http://www.apple.com/media/product1.jpg", "1c32c848e64741849e2049090e1c7688.jpg" |
| variations | variations | dictionary with dictionaries | Variation options. Keys are limited strings that contain the [variation-id]. | "color", "size", "material" |
| name | [variation-id].name | string | Variation name. | "Color", "Size", "Material" |
| options | [variation-id].options | dictionary with dictionaries | Keys are limited strings that contain the [option-id]. | "red", "large", "wood" |
| [option-id] | [variation-id].options.[option-id] | string | Option name. | "Green", "Yellow", "Large", "Wood" |
| variation | variation | dictionary with strings | This products variations and options combination. Keys are limited strings that contain the [variation-id]. | "color", "size", "material" |
| [variation-id] | variation.[variation-id] | string | The [option-id] for this [variation-id]. Only needed if this is a variation product (variationMaster not null). The [variation-id] and [option-id] should be available for this variation master. | "red", "large", "wood" |
| variationMaster | variationMaster | uuid | This variations' master product uuid. Defines whether this is a master or variation product, if empty it's a master product. | "06429e75a8ea11de82c09314b8ee4e5a" |
Product Variations Resource
URL Endpoints
| Endpoint | Supported Metods |
|---|---|
| /[store-handle]/api/v2/webstore/products/[product-uuid]/variations.json | GET |
| /[store-handle]/api/v2/webstore/products/[product-uuid]/variations/[variation-uuid].json | GET, PUT, DELETE |
Data Structure
Data structure of variation products is identical to regular products.
GET
/[store-handle]/api/v2/webstore/sales/products/d118000ea240481d801b265846630bf5/variations.json
/static/support/documentation/examples/variations.json