Search overrides & merchandising

Pin specific products to specific positions for a search term, category, tag or brand page — hardcoded merchandising on top of the normal ranking. The advanced companion to Sync your catalog.

The model

A product ranking override is scope + products in order:

• pageType — where it applies: SEARCH, CATEGORY, TAG, or BRAND.
• url — the scope value(s): search term(s) for SEARCH, or entity slug(s) for CATEGORY/TAG/BRAND.
• productIds — the products to pin, in display order (position 1 = first).
• validFrom / validTo — optional time window (e.g. a campaign).

Pin products for a search term

Put product 2002 first for searches of "iphone 13":

curl -X POST https://zopping.com/api/catalogue-service/product-ranking \
  -H "Authorization: Bearer $ZOPPING_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "organizationId": "<org-id>",
    "pageType": "SEARCH",
    "url": ["iphone 13"],
    "productIds": [2002, 1001, 3003],
    "languages": "en"
  }'

The order of productIds is the ranking — first id shows at position 1.

Reorder or update

PUT the same ranking with a new productIds order:

curl -X PUT https://zopping.com/api/catalogue-service/product-ranking \
  -H "Authorization: Bearer $ZOPPING_TOKEN" -H "Content-Type: application/json" \
  -d '{"id": 42, "organizationId": "<org-id>", "productIds": [1001, 2002, 3003]}'

List existing overrides

curl "https://zopping.com/api/catalogue-service/product-ranking?organizationId=<org-id>&pageType=SEARCH&activeNow=true&include=entity" \
  -H "Authorization: Bearer $ZOPPING_TOKEN"

activeNow=true returns only time-valid overrides; include=entity expands the pinned products in the response.

Use it for

• Sponsored placements and seasonal pushes (with validFrom/validTo).
• Fixing a top result for a high-intent term.
• Hand-curating a category's first row.

Reference: Catalog.