Skip to content

Merchandiser API: Sorted Collections and Product Metrics

Two APIs connect your own systems to Merchandiser: one returns the sorted products of a collection, the other takes in the sales of your products.

Overview

Stores on a platform with a ready-made integration do not need the API: Merchandiser writes the product order to the platform for them. The API is for everything else.

Collections API
Read access to your collections and to the sorted products of each. For custom platforms and headless storefronts. No token; requests are identified by your account UID.
Product Metrics API
Write access to the sales metrics of your products. For sending online and in-store sales from an ERP or a data warehouse. Requires a token.

All addresses below start with the base URL. Your account UID and the ready-to-copy address of every collection are shown on the API Integration page of the panel.

Base URL

https://api.merchandiser.com.tr/v1

Collections API

List the Collections of a Type

GET https://api.merchandiser.com.tr/v1/accounts/{account_uid}/collections/{type}

{type} is one of category, brand, list, page, widget or other. The answer lists the active collections of that type:

Response sample (shortened)

{
  "type": "category",
  "total_records": 2,
  "collections": [
    {
      "id": 1042,
      "name": "Women > Jackets",
      "type": "category",
      "code": "women-jackets",
      "path": "/women-jackets",
      "smart": false,
      "sort_type": {"id": 7, "uid": "0b0c…", "name": "Merchandiser AI"},
      "updated": 1760000000.0
    }
  ]
}

code is the identifier your store uses for the collection. updated is the time of the last sort as a Unix timestamp; compare it with the value you saw last to find out whether a collection needs to be fetched again.

Get the Sorted Products of a Collection

GET https://api.merchandiser.com.tr/v1/accounts/{account_uid}/collections/{type}/{code}?page=1&size=50

A collection can also be addressed by its own UID: 

GET https://api.merchandiser.com.tr/v1/collections/{collection_uid}
page
The page to return, starting at 1.
size
The number of products per page. 50 when it is left out.
expand
true returns each product with its name, brand, prices, rating, address and image. Without it, a product is its SKU and its position.
ws_code
true returns the ERP code of each product in the sku field instead of its SKU.
color, gender
Return only products of these colors or genders. Both can be repeated.
sort_by
The UID of a sort type. Returns the collection ordered by that sort type instead of its saved order.

Response sample

{
  "collection": "Women > Jackets",
  "code": "women-jackets",
  "type": "category",
  "id": 1042,
  "page": 1,
  "size": 50,
  "total_pages": 3,
  "total_records": 128,
  "has_next": true,
  "has_prev": false,
  "products": [
    {"sku": "AB-123", "position": 1},
    {"sku": "AB-124", "position": 2}
  ]
}

Products are returned in their sorted order, pins included. Only products that are in stock are returned. Request the next page while has_next is true.

With expand=true, each product carries these fields as well: name, brand, sale_price, list_price, discount_rate, currency, rating, reviews, url and image_url.

Limits and Errors

Requests are rate limited per IP address. Every answer carries an X-Api-Call-Limit header with the number of requests you have left in the current window. Tell us the addresses of your servers and we will exempt them from the limit.

400
A parameter is not valid, for example a page or size that is not a number.
404
The account or the collection does not exist or is not active.
429
Too many requests. Try again later.

Product Metrics API

This request updates the sales metrics of your products in bulk. It is authenticated with a product metrics token, which is issued for your account on request. 

POST https://api.merchandiser.com.tr/v1/products/metrics
Content-Type: application/json
Authorization: Bearer <YOUR-PRODUCT-METRICS-TOKEN>

The body is a list of up to 1,000 objects. Every object needs an sku and at least one metric. Metrics can be sent as numbers or as numeric strings and must not be negative. A metric you do not send is left untouched. SKUs that do not exist in your account are reported back and never created.

sku
The SKU of the product to update. Required.
daily_purchase, weekly_purchase, monthly_purchase
Online sales of the last day, week and month.
daily_offline_purchase, weekly_offline_purchase, monthly_offline_purchase
Offline (store) sales of the last day, week and month.
total_daily_purchase, total_weekly_purchase, total_monthly_purchase
Online and offline sales together.

How Totals Are Kept in Sync

  • Sending an online metric overwrites it and recalculates the total of that period as online plus offline, using the offline value already stored (or 0 when there is none).
  • Sending an offline metric works the same way, using the stored online value.
  • Sending a total overwrites that total. If you send a total together with the online or offline metric of the same period, the total you sent wins.

Request sample

[
  {"sku": "AB-123", "daily_purchase": 4, "daily_offline_purchase": 6},
  {"sku": "AB-124", "weekly_purchase": 18, "monthly_purchase": 63},
  {"sku": "AB-125", "total_weekly_purchase": 42}
]

The same request with cURL

curl -X POST https://api.merchandiser.com.tr/v1/products/metrics \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-PRODUCT-METRICS-TOKEN>" \
  -d '[{"sku": "AB-123", "daily_purchase": 4, "daily_offline_purchase": 6}]'

Response sample

{
  "status": 200,
  "elapsed": 0.14,
  "message": "Given product metrics processed successfully",
  "errors": ["1 SKU(s) were not found for this account: AB-999"],
  "data": {
    "received": 4,
    "updated": 3,
    "skipped": 1,
    "unknown_skus": ["AB-999"]
  }
}
data.received
The number of items in the request.
data.updated
The number of products whose metrics were updated.
data.skipped
The number of items that were not applied: invalid items and unknown SKUs.
data.unknown_skus
The SKUs that do not exist in your account (the first 50).
errors
The reason for every skipped or partly invalid item. An answer with errors is still a 200: the valid items are applied.

Errors

400
The token is missing, or the body is not a list of objects.
403
The account is suspended.
404
The token is not valid.
413
More than 1,000 items were sent in one request.
415
The Content-Type header is not application/json.

What the Sales Are Used For

The metrics you send become ranking signals. A rule can rank by online sales alone or by the totals, so products that sell well in your stores can rise on your website too. Merchandiser AI learns from the totals when they are present.

Frequently Asked Questions

Do I need the API to use Merchandiser?

Not on a platform with an integration, where the order is written to the store for you. The API is for custom and headless storefronts, and for sending sales from your own systems.

Is the collections API authenticated?

No token is needed to read a collection. Requests are identified by your account UID and are rate limited. The product metrics API requires a token.

Can I send in-store sales to Merchandiser?

Yes. The product metrics API accepts online sales, offline (store) sales and their totals for the last day, week and month of each product.

Want to see this on your own collections?

Request a demo and we'll show you how it works with your catalog and your store platform.

Request Demo View Plans