How to integrate merchandising by API

This guide shows you how to fetch product strategies from AB Tasty's merchandising API and display them on your site.

Overview

The Merchandising feature displays curated product lists (strategies) configured in the AB Tasty back-office.

Prerequisites

Two API calls are required:

1. Resolve a strategy UUID from a category ID (optional : skip if the UUID is already known)

2. Fetch the strategy items with optional filtering, faceting and pagination

Base URL: https://uc-info.eu.abtasty.com/v1

Authentication

All requests require a JWT in the Authorization header :

Authorization: Bearer <token>

Endpoints

1

Resolve strategy UUID from category ID

GET /reco/{site_id}/merch/category_id/{category_id}

Use this endpoint to retrieve the strategy UUID from a category ID before calling the items endpoint.

Path parameters

Parameter	Type	Description
site_id	integer	Your AB Tasty site identifier
category_id	string	The category identifier

Response

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Use the returned uuid as the merch_id parameter in the items endpoint below.

When no strategy is linked to the given category_id, the endpoint returns 200 with {"uuid": null} instead of a 404 error.

Response statuses

Response Status	Message	Reasons
200	OK	Always returned, even when no strategy is found (uuid is null)
403	Forbidden	Missing token, invalid/expired token, or site_id mismatch

2

Fetch merchandising strategy items

GET /reco/{site_id}/merch/{merch_id}

Returns a ranked list of products for a specified strategy, with optional filtering, faceting and pagination.

Path parameters

Parameter	Type	Description
site_id	integer	Your AB Tasty site identifier
merch_id	string	UUID of the merchandising strategy

Query parameters

Parameter	Type	Default	Description
variables	string	-	Comma-separated key:value pairs injected into the strategy template (e.g. category_id:shoes)
fields	string	-	Comma-separated list of product fields to return (e.g. id,title,price). id is always included.
page	integer	1	Page number (1-indexed). Ignored when offset is also provided.
offset	integer	0	Zero-based item offset. Takes precedence over page.
limit	integer	20	Number of items per page.
facets	boolean	false	Set to true to include facet counts in the response.
filters[f][]	string	—	Filter on field f. Repeat for multiple values (OR within a field, AND across fields). See filter syntax below.
output_format	string	json	Response format. Accepted values: json, csv.
delimiter	string	,	CSV delimiter (only used when output_format=csv

Filter syntax

Filters use PHP-style bracket notation. Two syntaxes are supported based on the operation needed.

Combining rules

• Multiple values on the same field → combined with OR

• Filters on different fields → combined with AND

• Field names must match ^[A-Za-z_][A-Za-z0-9_]*$ (letters, digits and underscores only)

Syntax 1 : Equality / IN (empty index [])

Use filters filters[field][]=value for equality matching. Repeat the parameter on the same field name to produce an IN (OR) filter.

Operation	Query string	Behaviour
Equals	filters[available][]=1	available = 1
IN (OR)	filters[category][]=shoes&filters[category][]=boots	category IN ('shoes', 'boots')

Syntax 2 : Comparison operators (indexed entries)

Use filters[field][{idx}][operator] + filters[field][{idx}][value] for >, <, >=, <= comparisons. Use incrementing indices (0, 1, …) to stack multiple conditions on the same field.

Allowed operators: >, <, >=, <=

Operation	Query string
Greater than	filters[price][0][operator]=>&filters[price][0][value]=10
Less than or equal	filters[price][0][operator]=<=&filters[price][0][value]=500
Range (min + max)	filters[price][0][operator]=>=&filters[price][0][value]=10&filters[price][1][operator]=<=&filters[price][1][value]=500

Combined example in-stock shoes priced between €10 and €500:

filters[available][]=1
&filters[category][]=shoes&filters[category][]=boots
&filters[price][0][operator]=>=&filters[price][0][value]=10
&filters[price][1][operator]=<=&filters[price][1][value]=500

Response (JSON)

{
  "name": "strategy-name",
  "items": [
    {
      "id": "product-123",
      "title": "Running Shoes",
      "price": 89.99
    }
  ],
  "total_items": 248,
  "total_pages": 13,
  "current_page": 1,
  "limit": 20,
  "has_next": true,
  "facets": {
    "category": {
      "shoes": 84,
      "boots": 40
    },
    "available": {
      "1": 248
    }
  }
}

Response fields

Field	Type	Description
name	string	Internal name of the merchandising strategy
items	array	Ordered list of products for the requested page
total_items	integer	Total number of products matching the strategy and active filters
total_pages	integer	Total number of pages given the current limit
current_page	integer	Current page number (1-indexed)
limit	integer	Number of items per page used for this response
has_next	boolean	Whether a next page exists
facets	object	Facet counts by field and value. Only populated when facets=true

Response statuses

Response Status	Message	Reasons
200	OK
400	Bad Request	Strategy not found for this merch_id; invalid filter field; query execution error
403	Forbidden	Missing token, invalid/expired token, or site_id mismatch
422	Unprocessable Entity	variables is not valid JSON; fields is not a valid JSON list; unknown output_format
503	Service Unavailable	Request exceeded the 10-second global timeout

Typical integration flow

1. (Optional) Resolve UUID
   GET /reco/{site_id}/merch/category_id/{category_id}
   → { "uuid": "3fa85f64-..." }

2. Fetch first page of items
   GET /reco/{site_id}/merch/{uuid}?variables=category_id:shoes&fields=id,title,price&limit=20&facets=true
   → items[], facets{}, total_items, total_pages

3. Display facets and let user apply filters
   GET /reco/{site_id}/merch/{uuid}?...&filters[category][]=shoes&filters[available][]=1
   → filtered items[] and updated facets{}

4. Paginate
   GET /reco/{site_id}/merch/{uuid}?...&page=2
   — or —
   GET /reco/{site_id}/merch/{uuid}?...&offset=20&limit=20

Notes

• The id field is always returned regardless of the fields parameter.

• When both offset and page are provided, offset takes precedence.

• Facet computation adds overhead-only request facets=true when you need to render facet counts.

• Field names in filters and facets must match the fields configured for the strategy in the AB Tasty back-office.