Skip to content

Fetch Products (V2) ​

Use these endpoints to get a page of products, or to get one product with all its details. V2 products have variant groups and SKUs.

NOTE

For a customer storefront, use the Storefront API. It returns only products that are not archived.

Endpoints ​

EndpointMethodPath
Fetch productsGET/v2/products
Fetch one productGET/v2/products/{productId}
Fetch one product by slugGET/v2/products/slug/{slug}
Fetch similar productsGET/v2/products/similar/by/category/{productId}
Fetch top selling productsGET/v2/products/top-selling

Headers ​

json
{
  "X-MerchantApiKey": "MERCHANT_API_KEY"
}

These endpoints are public in the API specification. The API uses the X-MerchantApiKey header to find the store.

Query parameters for GET /v2/products ​

Pagination and sorting ​

ParameterTypeDefaultDescription
pageinteger0Page number. The first page is 0.
limitinteger100Number of products on each page.
sortFieldParamstringCREATED_ATField to sort by, for example NAME, PRICE or CREATED_AT.
sortDirectionParamstringDESCASC or DESC.
withCursorbooleanfalseSet to true to use cursor pagination.
cursorstringCursor from the previous response (ISO 8601 instant). Use it with withCursor=true.

Filters ​

ParameterTypeDescription
searchstringSearch text for the product name or description.
category / categoryNamestringID or exact name of the category.
unitCategorystringUnit category. Separate more than one value with commas.
brand / brandNamestringID or exact name of the brand.
color / colorNamestringID or exact name of the color.
createdAtFrom / createdAtTostringDate range for the creation date (ISO 8601).
minPrice / maxPricenumberPrice range.
availabilitybooleantrue returns products that have stock.
lowStockbooleantrue returns products at or below their reorder level.
statusstringProduct status.
minRatingnumberMinimum rating.
archivedbooleanArchive status. The default is false.
tagsstringTags. Separate more than one value with commas.

NOTE

The API does not return archived products unless you set archived=true.

Example request ​

javascript
fetch('https://api.shopsynch.com/v2/products?page=0&limit=20&search=camera&sortFieldParam=PRICE&sortDirectionParam=ASC', {
  method: 'GET',
  headers: { 'X-MerchantApiKey': 'MERCHANT_API_KEY' }
})
  .then(response => response.json())
  .then(data => console.log(data));

Response 200 ​

The list endpoint returns products, total, totalPages and currentPage in the data field. currentPage starts at 1. The one-product endpoints return one product in the data field.

json
{
  "id": "679f8f5a3b5f2173201c2582",
  "name": "Professional DSLR Camera",
  "slug": "professional-dslr-camera-0001",
  "productType": "VARIABLE",
  "price": 899.0,
  "effectivePrice": 899.0,
  "isOnSale": false,
  "attributes": {
    "Megapixels": "24.2 MP",
    "Sensor Type": "CMOS"
  },
  "variantGroups": [
    {
      "attributeName": "Color",
      "attributeValue": "Graphite Black",
      "skus": [
        { "price": 899.0, "quantityInStock": 45, "attributes": { "Storage": "64GB" } }
      ]
    }
  ],
  "availableQty": 45,
  "isArchived": false
}

See Product fields for the description of the fields. The merchant response also has the cost price and the profit.

Legacy fields ​

A V2 product also has some fields from the removed V1 API, such as ramSize, storage, size, color and variations. These fields are deprecated. Use attributes instead.

Build with joy