# Welcome to AB Tasty documentation Testing new features, accelerating output, enhancing experiences. It all takes a mindset of optimization. It all takes trial, then better. {% embed url="" %} Get a demo Join our User Community ## Your other resources
Enhance your workflow with AI-driven featuresEvi, our suite of intelligent tools helps you move faster, make better decisions, and focus on what matters most./files/qNxWPPL353BQH97pAcNU/spaces/hZIDRsh66I8ikipjy42H/pages/iE7tkiU54rL5H9qImTVH
Developer documentationUse AB tasty’s API, SDK, and developer tools to build custom integrations, streamline workflows, and create tailored experimentations./files/cxxVfW97hexn6zrq1O7B/spaces/dOXiDeTDDJGZusc7Dwd3/pages/1et4I1OtTWJ8Uj5Eatlg
Discover our widgetsElevate your website’s functionality and engagement effortlessly with AB Tasty's widgets./files/n6tTayqCwZIsKs2sG8Euhttps://docs.abtasty.com/help-center
Release noteLooking for a page full of features to help you work smarter and faster? This is where you’ll always find what’s new with AB Tasty./files/fLuqSuOdBnRUDalHiWuXhttps://www.abtasty.com/new-features-2025/
Statistical CalculatorWant to achieve statistical reliability quickly?
Use our A/B Test Calculator and Minimum Detectable Effect Calculator.		/files/F0xhJJpPnrw2aX3ND95Dhttps://www.abtasty.com/sample-size-calculator/
BlogExplore our articles, e-books, case studies, and webinar replays to maximize your use of AB Tasty./files/6tFSuz96W31GrNk12qgRhttps://www.abtasty.com/resources/
## Popular articles {% content-ref url="/pages/mHQ8eOPURg4SyQDO2y7h" %} [Set up the AB Tasty Tag in 5 Minutes](/account/tag-integration/implement-ab-tasty-tag/set-up-the-ab-tasty-tag-in-5-minutes) {% endcontent-ref %} {% content-ref url="/pages/94HMhTKQNhUhd0lUkXr0" %} [Goals step](/web-experimentation-and-personalization/campaign-flow-goals-step) {% endcontent-ref %} {% content-ref url="/pages/NYsELROHY1WRUxuLT44D" %} [Campaign duplication](/web-experimentation-and-personalization/campaign-creation-and-dashboard/campaign-duplication) {% endcontent-ref %} ## New articles {% content-ref url="/pages/p00Pgjlpcx5MyeOQFVIe" %} [Evi Ideas](/web-experimentation-and-personalization/campaign-creation-and-dashboard/how-to-create-a-campaign/experimentations/ideas-copilot) {% endcontent-ref %} {% content-ref url="/pages/hPDMFKbdu76ZnJw6uE3R" %} [Evi Analysis](/reporting-and-performances/reporting/campaign-reporting/analysis-copilot) {% endcontent-ref %} {% content-ref url="/pages/wKSxNb5eA1jpvjxBtkJ1" %} [Import Audience data from any 3rd-party solution (Custom pull)](/integrations/custom-integrations/import-audience-data-from-any-3rd-party-solution-custom-pull) {% endcontent-ref %} {% content-ref url="/pages/4FapgxibUFzxe75gBR6s" %} [Even allocation](/web-experimentation-and-personalization/traffic-allocation/even-allocation) {% endcontent-ref %} {% content-ref url="/pages/7ApTifNueVhB0jvhhp9u" %} [Using Evi Content](/web-experimentation-and-personalization/editors-and-widget/visual-editor/using-the-editor-copilot) {% endcontent-ref %} {% content-ref url="/pages/Y45e89efCmPs12A7bZLR" %} [Chrome extension](/web-experimentation-and-personalization/editors-and-widget/chrome-extension) {% endcontent-ref %} # Getting started Welcome to **AB Tasty Commerce**. Commerce brings catalog management, ranking rules, recommendations, merchandising, and search together in a single app. This page mirrors the in-app **Get started** onboarding so you can go from an empty account to a live, data-driven catalog. {% hint style="info" %} **What changed:** Commerce is the successor to the former **Recommendations & Merchandising** and **Search** products. The underlying concepts (strategies, rules, ranking blocks, RECO/MERCH ids) are the same, they are now unified under one **Commerce** app and navigation. {% endhint %} ### The Getting started checklist
The onboarding screen presents a checklist organized into three groups. Each group shows its own progress (for example, `0/3` or `2/2` completed). Work through them top to bottom. #### 1. Connect your catalog Bring your products into Commerce. This group has three steps: | Step | What you do | | ------------------------------ | ----------------------------------------------------------------------------- | | **Connect catalog source** | Choose where your product data comes from (see below). | | **Set catalog basics** | Define the core settings for how your source catalog is imported. | | **Import your catalog fields** | Map the product fields you want available for rules, filters, and strategies. | {% hint style="success" %} Once your catalog source is connected and the first synchronization completes, your products appear under **Catalog** (the header shows the product count and the last update, for example "Last update: about 8 hours ago from Shopify"). {% endhint %} #### 2. Unleash algorithmic power Feed performance data into Commerce so the ranking algorithms can use real metrics such as views, purchases, and revenue: | Step | What you do | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | **Connect analytics source** | Link your analytics tool. | | **Enrich catalog with analytics data** | Attach behavioral metrics (for example `pageviews_last_30_days`, `revenues_last_30_days`) to your products. | #### 3. Unleash personalization power Enable the front-end signals that make recommendations and merchandising personal: | Step | What you do | | --------------------------------- | ------------------------------------------------------------------------------------------------- | | **Install JS tag** | Add the AB Tasty tag to your site so visitor events are collected. | | **Set visitor context variables** | Define the dynamic context (such as page type, category, viewed items) passed to your strategies. | {% hint style="info" %} Groups can be completed in any order, but connecting the catalog first is recommended, most other steps build on the products it imports. {% endhint %} # Recommendations # Create a recommentation strategy A **Recommendation** strategy generates a dynamic product list from user behavior, context, or product relationships, and displays it at a specific location on the customer journey (homepage, category page, product page, and so on). {% hint style="info" %} **What changed:** Recommendations come from the former **Recommendations & Merchandising** product and keep the same model. The builder has been refreshed, ranking blocks are now grouped into **Basics / Dynamic / Customizable**, and the former drag-and-drop "RANKING BLOCKS" / "CUSTOM RULES" panels are replaced by **New rule** and **Global customization**. Under the hood each strategy still carries a `RECO_ID` for API deployment. {% endhint %} ## Creating a recommendation ### Create with AI **Create with AI** lets you describe the strategy in natural language and have Commerce generate it. {% stepper %} {% step %} #### Click **Create with AI** Click **Create with AI** to start the guided flow. {% endstep %} {% step %} #### Enter a description
Enter a description and click **Generate** (the button stays disabled until you type a prompt. The generated strategy opens in the builder, where you can review and refine it. {% endstep %} {% endstepper %} ### Guided creation {% stepper %} {% step %} #### **Create recommendation** Click **Create recommendation +** to start the guided flow. {% endstep %} {% step %} #### Choose the location The location matters because it determines which context variables (such as `categoryId` or `productId`) are available to your rules, and which presets are offered next.
{% endstep %} {% step %} #### Pick a starting point
The next modal, **Pick a strategy to start from…**, offers: * **Basics → Empty strategy**: start from scratch. * **Recommended for \**: placement-aware presets, for example: * **Best sellers**: push the products with the best number of sales over the last 7 / 14 / 30 days. * **Most consulted products**: the most viewed products over the last 7 / 14 / 30 days. Picking a preset opens the builder pre-filled with a matching rule; **Empty strategy** opens an empty builder. {% endstep %} {% step %} ### Add Rules, Pins, and customizations
The left **configuration panel** of the **stragey builder** is where you assemble the strategy. An empty strategy prompts you to *"Kick off your strategy by adding a first rule…"* with **New rule +**. The panel is organized into: * **(Rules)**: one or more ranking blocks, each named **Rule #N**. * **Pins** → **Pin product(s)**. * **Global customization** → **New global customization (filter, exclude, sort…)**. * **Display rules**: **Results maximum** and **Display threshold**. The right panel, **Your strategy results**, renders a live preview of what the configuration returns {% endstep %} {% step %} ### Save and deploy You can now save and deploy the strategy {% endstep %} {% step %} ### Performance reporting To measure performance, open the **Recommendations Reporting** dashboard.
Reporting (**Recommendations → Reporting**) tracks exposure and revenue impact, KPIs include "Part of the catalog displayed", "Visitor exposition rate", and "Exposed visitors click rate", with **Compare**, **Filters**, and sections for **Top products**, **Pinned products**, **Top categories**, **Top strategies**, and **Top brands**. {% endstep %} {% endstepper %} ## The strategy builder #### Ranking blocks (New rule) Click **New rule +** to add a ranking block, the main source of products for the rule. Blocks are grouped: #### Basics | Block | What it returns | | ------------------------------ | ---------------------------------------------------- | | **Best sellers** | Products that did the best sales over the last days. | | **Most consulted products** | Products most viewed over the last days. | | **Repurchase recommendations** | Products the user is likely to buy again. | #### Dynamic | Block | What it returns | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | **Products associated to…** | Products often bought together with another product. | | **Products viewed together with…** | Products often viewed together with another product. | | **Products semantically similar to…** | Products alike in meaning (an *on-demand* block, when not yet activated it shows **Enable**, which opens the external enablement step). | | **semantic** | A custom semantic rule. | #### Customizable | Block | What it returns | | -------------------------- | --------------------------------------------------- | | **Products sorted by…** | Products sorted by the catalog field you choose. | | **Products from variable** | Products supplied by a dynamic contextual variable. | {% hint style="info" %} The **Dynamic** blocks are powered by machine-learning algorithms. For how *Products associated to…*, *Products viewed together with…*, and *Products semantically similar to…* are computed (co-occurrence, TF-IDF, semantic similarity), see [Algorithms](https://file+.vscode-resource.vscode-cdn.net/Users/didier/repos/abtasty/commerce/docs/commerce/04-creating-strategies/recommendations/algorithms/). For the runtime inputs used by *Products from variable*, see [Dynamic contextual variables](https://file+.vscode-resource.vscode-cdn.net/Users/didier/repos/abtasty/commerce/docs/commerce/04-creating-strategies/recommendations/dynamic-contextual-variables/). {% endhint %} #### Pins In the **Pins** section, **Pin product(s)** forces specific products into fixed positions at the top of *this* strategy. {% hint style="info" %} A **Pin** boosts products to the top of a single strategy. To promote or demote products *globally across every strategy*, use the dedicated [Boost & Bury](https://file+.vscode-resource.vscode-cdn.net/Users/didier/repos/abtasty/commerce/docs/commerce/03-creating-rules-boost-and-bury/) rules instead. {% endhint %} #### Global customization ![Global customization options: Filter, Exclude, Diversification, Shuffle, Sort by, Filter if.](https://file+.vscode-resource.vscode-cdn.net/Users/didier/repos/abtasty/commerce/docs/commerce/04-creating-strategies/recommendations/images/custom-rules.png) The **Global customization** section adds rules that apply across the strategy. Use **New global customization (filter, exclude, sort…)** to add one of: | Option | What it does | | ------------------- | ----------------------------------------------------- | | **Filter** | Filter products based on dynamic, personalized rules. | | **Exclude** | Exclude specific products from the rule. | | **Diversification** | Reorganize products to optimize diversity. | | **Shuffle** | Randomize the order of product results. | | **Sort by…** | Reorganize results by sorting on a field. | | **Filter if…** | Only include some products if a condition is met. | #### Display rules | Setting | Default | What it does | | --------------------- | ------- | -------------------------------------------------------------- | | **Results maximum** | `12` | Maximum number of products the strategy returns. | | **Display threshold** | `0` | Minimum number of products required before the block is shown. | # Repurchase recommendation algorithm # Integrating & calling the repurchase algorithm For each product a user has already bought, the algorithm estimates its repurchase cadence and surfaces the product when the user is approaching their next forecasted repurchase date. {% hint style="info" %} The API does **not** fetch the user's purchase history for you. It doesn't know the user and reads no purchase database. The caller (site tag, integration, CRM job, client backend) fetches the history upstream and passes it on every request. See Provide the history on every request. {% endhint %} ### Provide the history on every request The value of `purchase_history` is an object mapping each product id to a list of ISO 8601 purchase timestamps. ```json { "variables": { "purchase_history": { "SKU-001": ["2025-01-15T00:00:00", "2025-04-20T00:00:00", "2025-07-10T00:00:00"], "SKU-002": ["2025-03-01T00:00:00"] } } } ``` **Constraints** * Type: a dictionary of `{ string : list of strings }`. * Keys: the product's `id` in the catalog (the same id as in `items`). * Timestamps: ISO 8601 strings (`datetime.fromisoformat`). Time zones are accepted; a missing time zone is interpreted as UTC. * **Cap: 50 products.** Beyond that, only the 50 with the most recent last purchase are kept; the rest are dropped and a warning is logged. * An empty list (`"SKU": []`) and an empty dictionary (`{}`) are valid; they simply produce no recommendations. {% hint style="warning" %} Requests carrying a `purchase_history` are inherently per-user, so cache keys are effectively individual. Cache misses are expected and acceptable for this strategy. {% endhint %} ### What the source returns The `repurchase` builtin behaves like a catalog source: it returns product rows, filtered to the products that are repurchase-eligible for this user. Each row carries all the usual `items` columns (`id`, `name`, `price`, `img_link`, `absolute_link`, `categories`, engagement metrics, and so on) **plus three computed columns**. | Column | Type | Meaning | | -------------------------- | -------------- | ------------------------------------------------------------------------------------------------- | | `repurchase_frequency` | FLOAT (days) | Estimated cadence D actually used: the user's own cadence, or the site-wide average as a fallback | | `days_since_last_purchase` | INT (days) | Days elapsed since the user last bought this product | | `urgency_score` | FLOAT `[0, 1]` | Peaks at `1.0` at the forecasted repurchase date, tapering to `0` at the window edges | By default the preset sorts on `urgency_score DESC` and returns 12 products. You can sort or filter on any column, including the three computed ones. ### Errors and edge cases #### Validation errors (HTTP 422) The value of `purchase_history` is validated at the API boundary. A malformed value returns `422` with an explicit message. | Cause | Message | | --------------------------------- | -------------------------------------------------------------------------------- | | Value is not an object | `Variable purchase_history must be an ITEMS_HISTORY` | | A key is not a string | `Variable purchase_history keys must be strings` | | A product's value is not a list | `Variable purchase_history[] must be a list` | | A timestamp is not a string | `Variable purchase_history[] must contain ISO 8601 strings` | | A timestamp is not valid ISO 8601 | `Variable purchase_history[] contains invalid ISO 8601 timestamp: ''` | #### Empty or reduced results (no error) These situations raise no error; they just yield fewer or zero rows, which lets you compose a fallback with `union_all`. | Situation | Behavior | | ------------------------------------------ | ------------------------------------------------------------------- | | `purchase_history` missing or empty | Source returns 0 rows. Combine with a `union_all` fallback. | | Product bought once, no site-wide average | Product excluded (cadence not estimable). | | Product in history but absent from catalog | Product excluded (filtered out naturally). | | Product outside the repurchase window | Product excluded (`urgency_score` = 0). | | No eligible product | Empty result set; plan a rule-level fallback. | | Unparseable timestamps for a product | That product is skipped (warning logged); the others are processed. | {% hint style="info" %} Because a missing variable or an empty result returns nothing rather than erroring, wrap the repurchase source in a `union_all` with a fallback strategy so users always get recommendations. {% endhint %} #### Structural limitations * **No `GROUP BY`.** The three computed columns are materialized at request time; an aggregation step drops them. The builtin is not meant to sit behind an aggregation. * **Not batch-precomputable.** The strategy depends on the per-request, per-user `purchase_history`. A precompute attempt fails explicitly with `VIRTUAL_SOURCE_NOT_PRECACHEABLE` rather than producing a wrong result. Repurchase is a real-time strategy. # How the repurchase algorithm decides This article explains **why** the algorithm recommends the products it does. For the practical side (the variable, builtin, preset, input/output contract, and errors), see Integrate & call the repurchase algorithm. ### The core intuition For each product in a user's purchase history, the algorithm: 1. Estimates **D**, the product's repurchase cadence in days. 2. Computes `days_since_last_purchase`, how long since the user last bought it. 3. Defines a **repurchase window** around D. 4. If the user is inside the window, the product is eligible and gets an urgency score; otherwise it's discarded. Eligible products are returned sorted by descending urgency. The idea: don't recommend a product right after it was bought (too early), nor indefinitely long after (the need is probably already covered), but around the moment the observed cadence says the user is due to buy again. ### Estimating the cadence D How D is estimated depends on the user's history **for that specific product**. #### Two or more purchases: use the user's own cadence Sort the purchase dates, take the intervals between consecutive purchases, and set D to their mean. > **Example.** Purchases on Jan 1, Mar 1, May 1 → intervals of 59 and 61 days → **D = 60 days.** The user's own cadence is used as-is, with no smoothing and no blending with the site-wide average. #### A single purchase: fall back to the site-wide average One purchase can't measure an interval, so the algorithm falls back to the product's site-wide average cadence (`avg_repurchase_interval_days`). * If a site-wide average exists → it becomes D. * If none exists (nobody has ever repurchased the product) → the product is **excluded**. There is no second fallback. {% hint style="info" %} The `repurchase_frequency` column always reflects the value **actually used**: the user's own cadence, or the site-wide average when it's the fallback. {% endhint %} ### The site-wide average The site-wide average is the safety net for users who bought a product only once. For each product: 1. Consider purchases over the **trailing 12 months**. 2. Keep only users who bought that product **at least twice** on distinct dates. A one-time buyer says nothing about cadence. 3. For each such user, compute their average cadence (mean of the intervals between their successive purchases). 4. The product's site cadence is the **mean of those per-user cadences**, where every multi-buyer weighs equally regardless of how many times they bought. Two product-level indicators come out of this: | Indicator | Meaning | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | `avg_repurchase_interval_days` | Average repurchase cadence across all multi-buyers. Null if no multi-buyer exists → the product can't serve as a fallback. | | `multi_buyer_count` | Number of users who bought the product ≥ 2 times (a confidence indicator). | These refresh with the catalog; a daily cadence is enough, since the 12-month aggregate barely moves day to day. ### The repurchase window Around the estimated cadence D, an eligibility window is defined as: ``` [ D − ratio × D , D + ratio × D ] ``` With the default `ratio` of **1/3**, the window is `[2/3·D, 4/3·D]`. {% hint style="warning" %} The original brief said "±30%", but the implemented default is one third (1/3 ≈ 33.3%). **1/3 is the authoritative value.** {% endhint %} A product is eligible only when the user sits inside the window: ``` days_since_last = today − date of last purchase eligible ⇔ D × (1 − ratio) ≤ days_since_last ≤ D × (1 + ratio) ``` Before the window (too early) → excluded. After it (overdue) → excluded. The `ratio` is configured once per site (`repurchase_window_ratio` in Redis) and is shared by every repurchase rule on that site, so it's **not** a per-rule parameter. Per-rule tuning happens through `where` / `sort` on `days_since_last_purchase` and `urgency_score`. > **Example.** D = 30 days → window `[20, 40]` days after the last purchase. ### The urgency score The urgency score is a symmetric triangular peak centered on D: `1.0` exactly at the forecasted date, falling linearly to `0` at the window edges. ``` score 1.0 | * | / \ | / \ | / \ 0.0 |______/ \______ low D high (D·(1−ratio)) (D·(1+ratio)) ``` The compact form: ``` urgency_score = max( 0 , 1 − |days_since_last − D| / (D × ratio) ) ``` With D = 30 and ratio = 1/3 (window `[20, 40]`): | Days since last purchase | Urgency score | | ------------------------ | ------------- | | 20 | 0.0 | | 25 | 0.5 | | 30 | 1.0 | | 35 | 0.5 | | 40 | 0.0 | Sorting `urgency_score DESC` therefore surfaces the products for which the user is closest to their repurchase date. ### End-to-end example Request excerpt: ```json { "variables": { "purchase_history": { "COFFEE-1KG": ["2026-01-05T08:00:00", "2026-02-04T08:00:00", "2026-03-06T08:00:00"], "FILTERS-100": ["2026-02-20T08:00:00"] } } } ``` Walkthrough as of **2026-04-02**, default ratio 1/3: * **COFFEE-1KG**: 3 purchases → intervals of 30 and 31 days → **D ≈ 30.5**. Last purchase 03/06 → `days_since_last ≈ 27`. Window ≈ `[20.3, 40.7]`. 27 is inside → eligible, `urgency_score ≈ 0.65`. * **FILTERS-100**: 1 purchase → fall back to the site-wide average. If `avg_repurchase_interval_days ≈ 45` → **D = 45**. Last purchase 02/20 → `days_since_last ≈ 41`. Window ≈ `[30, 60]`. 41 is inside → eligible. Had there been no site-wide average, it would be excluded. The response returns the eligible products with their catalog columns plus `repurchase_frequency`, `days_since_last_purchase`, and `urgency_score`, sorted by `urgency_score DESC` and limited to 12. {% hint style="info" %} Reminder: the API doesn't fetch history on its own. The caller supplies `purchase_history` on every request. See Integrate & call the repurchase algorithm for how to wire that up. {% endhint %} ### Defaults at a glance | Parameter | Default | Configured where | | -------------------------- | --------------------------------------- | -------------------------------------------------- | | Input variable | `purchase_history` (`ITEMS_HISTORY`) | Declared automatically on analytics unlock | | Cap on products in history | 50 (most recent kept) | Not configurable | | Window width `ratio` | 1/3 (≈ ±33%) → `[2/3·D, 4/3·D]` | Per site (`repurchase_window_ratio`), not per rule | | Site-wide average lookback | Trailing 12 months | Not configurable | | Multi-buyer filter | Users with ≥ 2 purchases of the product | Not configurable | | Default sort | `urgency_score DESC` | Editable in the rule | | Default volume | 12 | Editable in the rule | # Analyse your recommendation strategy performance In this tutorial, you will read through the Recommendations Report from top to bottom and draw your first conclusions about how your recommendation strategies are performing. ## Overview By the end, you will be able to: * Identify how much revenue your strategies are directly contributing * Understand how visitors are moving through your recommendation funnel * Spot which products, categories and strategies are driving the most impact * Adjust the report to focus on the data that matters most to you {% hint style="info" %} The report is populated from real visitor and transaction data. If your strategies were recently activated, give them a few days of data before working through this tutorial. {% endhint %} ## Analyse your recommendation strategy performance {% stepper %} {% step %} #### Open the report and set the date range Navigate to **Reporting** from the main navigation.
At the top of the page, check the **Last refresh** timestamp to confirm how recent the data is. Next, look at the date range picker in the top-right corner. It defaults to a 30-day window. For your first read-through, keep the default so you have enough data to see trends clearly.
{% endstep %} {% step %} #### Checking the Direct revenue contribution The performance overview section sits near the top of the report. The **Direct contribution estimate** banner shows an estimate of how much revenue your recommendation strategies helped generate.
Look at the four figures in the banner: 1. **Revenue helped:** the estimated euro value of sales influenced by a recommendation interaction, within your configured attribution window. 2. **% of total revenue:** the portion of your overall revenue generated from those influenced sales. 3. **Transactions helped:** the number of orders that involved a recommendation interaction. 4. **% of total transactions:** the proportion of all orders that included a recommendation interaction. {% hint style="info" %} Each figure shows a trend indicator next to it. An upward arrow means performance improved compared to the previous period; a downward arrow means it declined. {% endhint %} **Part of the catalog** displayed to the right of the banner indicates the percentage of products from your catalog that appear in at least one recommendation.
{% endstep %} {% step %} #### Analyzing visitor engagement with recommendations Scroll down to the **behavioral analysis** section. Two charts are displayed side by side.
1. **Visitor exposition rate:** shows the percentage of all site visitors who were shown at least one recommendation. The average value appears above the chart, while daily bars and a trend line display how this metric evolves over time. 2. **Exposed visitors click-rate:** shows the percentage of those visitors who clicked on a recommended product after seeing a recommendation. Interpreting these charts: * A **high exposition rate** combined with a low click-rate indicates that recommendations are frequently displayed, but the products shown are not compelling enough to generate clicks. * A **low exposition rate** indicates that your strategies are not reaching enough visitors. Verify that your strategies are deployed on the appropriate pages across both client-side and server-side campaigns. {% endstep %} {% step %} #### Follow the conversion funnel
To the right of the charts, find the **Conversion funnel**. It shows three stages: 1. **Product click**: visitors who clicked a recommended product. 2. **Add to cart**: how many visitors (who clicked on a recommended product), added the product to their cart (shown as a percentage of clicks). 3. **Transaction:** of those who clicked, how many visitors completed a purchase. Below the funnel, the transaction rate shows the overall purchase rate for visitors exposed to recommendations. {% hint style="info" %} A large drop between ***Add to cart*** and ***Transaction*** may indicate friction in your checkout flow. \ \ A large drop between ***Product click*** and ***Add to cart*** may suggest the recommended products are interesting to browse but not compelling enough to purchase {% endhint %} {% endstep %} {% step %} #### Compare visitor segments in the key indicators table
The key indicators table compares three visitor segments: 1. **All visitors**: everyone on your site 2. **Exposed visitors**: those who loaded a page with an active strategy 3. **Engaged visitors**: those who clicked a recommended product Look at the **Transaction rate**, **Revenue per visitor**, and **Average order value** bar charts below the table. Engaged visitors should show noticeably higher numbers across all three metrics. This will help demonstrate the value of moving visitors from passive exposure to active engagement. {% hint style="info" %} If engaged visitors show a much higher revenue per visitor than all visitors, your recommendations are working well once visitors interact with them. If the gap is small, it may suggest that engaged visitors were already high-intent buyers regardless of recommendations. {% endhint %} {% endstep %} {% step %} #### [Reviewing merchandising insights](#user-content-fn-1)[^1] In the **Merchandising Insights** section, you will see five tabs for: **Top 25 products**, Pinned products, **Top 25 categories**, **Top 25 brands** and **Top 25 Strategies**.
1. Start with **Top Products**. The table shows each product's displays, click-through rate, add-to-cart rate and revenue contribution. 2. Then click **Top Strategies** to see which individual strategies are driving the most revenue across all your campaign types: Web, Personalization, and Feature Experimentation in a single ranked view. {% hint style="info" %} If a product has a high display count but a low click-through rate, it may be overexposed or placed in an irrelevant context. Click **Export data** to download any table for further analysis. {% endhint %} {% endstep %} {% step %} #### Filter the report to a specific strategy or device
Narrow the report to investigate a specific area. Click **Filter** in the report header. A panel will open with four options: * **Locations**: filter by where on your site the strategy is placed. * **Strategies**: select one or more strategies to isolate their performance * **Product categories**: focus on a specific product category * **Devices**: compare performance on desktop vs. mobile {% hint style="info" %} Try filtering by a single strategy that caught your attention in Step 6. The entire report, all charts and tables, will update to reflect only that strategy's data. To return to the full view, click **Reset filters** at the top of the filter panel. {% endhint %} {% endstep %} {% step %} #### Adjust your attributions settings (optional) If the Direct contribution estimate in Step 2 seemed unexpectedly low or high, review your attribution settings. Click **Accuracy settings.** * **Attribution method:** controls how long after a recommendation interaction a transaction is still counted as influenced. The default is 24 hours. If your products have a longer purchase cycle, switching to 7 or 30 days will give a more complete picture. * **Cookie consent rate:** controls how the platform extrapolates data from consented visitors across your full visitor base. If you know your site's actual cookie consent rate, enter it here for a more accurate estimate. * After making changes, click **Save changes**. {% endstep %} {% endstepper %} [^1]: review top products and strategies # How to configure your email integration # How to configure Brevo integration Integrating Brevo with AB Tasty Recommendation and Merchandising {% stepper %} {% step %} ### Connect Brevo 1. In your Brevo account, generate an API Key**: SMTP & API > API Keys**, and copy it
1. In your AB Tasty account, go to **Settings > Integrations > Brevo**.
2. Paste the API key from Brevo into the API key field and click **Connect Brevo**.
{% endstep %} {% step %} ### Allow AB Tasty IPs on Brevo To allow AB Tasty to retrieve your Brevo contact attributes, make sure the following IP addresses are in your Acceptlist in your Brevo account or firewall settings: * `130.211.64.215` * `34.79.119.76` * `35.240.71.177` If these IPs are not authorized, the list of contact attributes may appear empty even though the integration is set up correctly. {% endstep %} {% step %} ### Deploy a recommendation in your email Now you can [deploy a recommendation in Brevo](/recommendations-and-merchandising/how-tos/how-to-deploy-a-strategy/how-to-deploy-a-recommendation-strategy-on-web/how-to-use-recommendations-in-emails-campaign/how-to-deploy-recommendation-with-brevo).
{% endstep %} {% endstepper %} {% hint style="info" %} For more personalization, you can create repeated variables so your emails feel like real one-to-one conversations. 🔗 [Learn more about Dynamic Content in Brevo](https://editor-beta.brevo.com/editor/newsletters/46#:~:text=Faites%20une%20liste,le%20contenu%20dynamique) {% endhint %} # How to configure SFMC integration This how-to explains how to insert a block of **dynamic product recommendations** into an SFMC (Salesforce Marketing Cloud) email by calling the Reco & Merch API from AB Tasty. This enables showing personalized products in real time, at the moment the email is opened. {% hint style="info" %} The SFMC integration is done via **API**. There is currently no dedicated cartridge available. {% endhint %} ### Prerequisites * Access to **Content Builder** in SFMC. * A **Reco & Merch template** already configured on AB Tasty. * A valid **Bearer Token** provided by AB Tasty. * Required variables available in your **Data Extension** (e.g. `EmailAddr`, `CodeEAN`). {% stepper %} {% step %} ### Connect SFMC to Reco & Merch 1. Go to **Settings > Integrations** in your AB Tasty Reco & Merch interface. 2. Click **Connect SFMC**. 3. A pop-up window will open to authenticate your SFMC account. 4. Once the connection is successful, your workspace will be linked to SFMC.
{% endstep %} {% step %} ### Deploy a recommendation in your email Now you can deploy a recommendation in SFMC. {% embed url="" %} {% endstep %} {% endstepper %} ### Notes on SFMC Below are some notes on SFMC **Performance** * Every email open triggers a live API call. * High-volume sends (500k+ subscribers) = high API traffic. * Ensure AB Tasty API quota is sufficient. **Fallback** * If the API fails, the block may be empty. * Always define a static fallback (e.g. “Top Sellers” block). **Security** * The **Bearer Token** is sensitive. * Rotate it regularly and avoid exposing it in shared snippets. * For extra safety, use a proxy to hide the token. **Data Extension alignment** * Verify all fields (`CodeEAN`, `EmailAddr`) exist for every subscriber. * If missing, the API call URL will be invalid → “400 Bad Request” errors. **Rendering** * Always test in **Preview & Test** with real subscriber profiles. * Validate rendering across multiple email clients (Gmail, Outlook, Mobile). # How to A/B test a recommendation strategy - For API clients This guide is dedicated to people who are implementing Recommendations manually via API and who want to be able to run remotely some A/B tests or personalizations. #### Requirements * Recommendations & Merchandising access * Feature Experimentation & Rollout access #### Differences with basic R\&M API integration: * Increased latency versus basic R\&M integration (+30 to 100ms) #### Overviews * [Usage overview](https://drive.google.com/file/d/1EaqRtzf6VXWiNoV8lJZCGHxf3SPeOpT3/view?usp=sharing) * [1st time technical implementation overview](https://drive.google.com/file/d/1ij8c1MXmrMc6n2qXocxaKaBZV94HHLn1/view?usp=sharing) ## Initial configuration {% stepper %} {% step %} ### Create a recommendation strategy Create the strategy of your choice and save it. {% endstep %} {% step %} ### Create a FE\&R flag 1. Go to Feature Experimentation > Flags 2. Click on **Create flag** 1. Name: `Reco_{block_name}` 2. Type: String 3. Click on **Save** {% endstep %} {% step %} ### Implement your strategy via API (Need a developer) 1. Select [the FE\&R SDK](https://app2.abtasty.com/settings/feature-experimentation/sdk-installation) that best fits you and configure it 2. Fetch FE\&R flags and retrieve the flag `Reco_{block_name}` which should contains the strategy id that you want to push on your specific recommendation block. Make sure that visitor id is of type a string 3. Call the Recommendations API by passing the value of the flag `Reco_{block_name}` as the strategy id. Don't forget to manually provide a fallback hardcoded strategy ID ``` https://uc-info.eu.abtasty.com/v1/reco/${SITE_ID}/recos/${strategy_id}?variables=${query}&fields=${fields} ``` 4. Use the results of the Recommendations API to display your recommendation block 5. Your code is ready to display your current strategy or future A/B tests {% endstep %} {% step %} ### Add FE\&R tracking (Need a developer) Implement the following trackers: * `click_on_product`: via an Event tracker ([documentation](https://docs.abtasty.com/server-side/concepts/universal-collect-1#:~:text=%7D%27-,Event,-This%20hit%20type)) * `add_product_to_card`: via an Event tracker ([documentation](https://docs.abtasty.com/server-side/concepts/universal-collect-1#:~:text=%7D%27-,Event,-This%20hit%20type)) * `purchase` : via a Transaction hit tracker ([documentation](https://docs.abtasty.com/server-side/concepts/universal-collect-1#:~:text=%7D%27-,Transaction,-A%20transaction%20hit)) Tracking documentation: [Tracking data with SDKs](https://docs.abtasty.com/server-side/sdks/key-features/tracking-data) or [Tracking with custom API calls](https://docs.abtasty.com/server-side/concepts/universal-collect-1) {% endstep %} {% step %} ### Create a FE\&R "Feature toggle" campaign {% hint style="info" %} This step is optional. If you don't do it, your default strategy will be the hardcoded strategy. It means that you will have to manually edit your code to deploy the winner of an A/B test. {% endhint %} 1. Go to Feature Experimentation > Campaigns 2. Click on "Create campaign" > "Feature toggle" 1. Name: `{block_name} deployment` 2. Type: Feature toggle 3. Folder: Pick the folder of your choice 3. Define your scenario 1. `Reco_{block_name}` = Your recommendation strategy ID 4. Define your goals, we recommend adding the 3 trackers 5. Keep default parameters for targeting & delivery strategy 6. Take your campaign live {% endstep %} {% endstepper %} ## Running an A/B test {% stepper %} {% step %} ### Create a variant recommendation strategy Create the strategy of your choice. You can duplicate your original strategy if you want not to start from scratch. {% endstep %} {% step %} ### Create a FE\&R "A/B test" campaign * Main information: * Name: `{block_name} A/B test` * Folder: folder of your choice for the campaign * Variations: * Original: Set flag `Reco_{block_name}` to original strategy id * Variation: Set flag `Reco_{block_name}` to your variant strategy id * Goals: Pick the goals you want to track * Targeting: All users * Traffic allocation: 50/50 {% endstep %} {% step %} ### Turn "A/B test" campaign live & pause "feature toggle" one * Set campaign `{block_name} A/B test` to "Live" status * Set campaign `{block_name} deployment` to "Pause" status {% endstep %} {% step %} ### Track your results Open the report for your campaign `{block_name} deployment` and check your results. {% endstep %} {% step %} ### Once your decision is taken, turn "feature toggle" campaign live and stop "A/B test" one * Set campaign `{block_name} deployment` to "Live" status * Set campaign `{block_name} A/B test` to "Pause" status {% endstep %} {% step %} ### Update your "Feature toggle" campaign with the ID of your winning strategy If you want to deploy your winning strategy, edit your deployment campaign `{block_name} deployment` by editing its scenario and setting `Reco_{block_name}` to your new winning strategy ID. {% endstep %} {% endstepper %} # How to A/B test recommendation strategies using AB Tasty Web Extensions This guide explains how to test two different recommendation algorithms or strategies on the same placement using AB Tasty for traffic splitting and experiment assignment cookie management. ### Overview The implementation relies on a clear separation of responsibilities. #### AB Tasty side: * Creates the A/B test * Generates 2 variations: A and B * Randomly assigns visitors * Sets an experiment assignment cookie #### Client or Agency side: * Reads the cookie set by AB Tasty * Interprets the assigned variation (A or B) * Triggers the corresponding call to the Merchandising & Recommendation API ### AB Tasty Implementation {% stepper %} {% step %} #### Create the test Create an A/B test on the desired scope (product page, homepage, listing page, etc.) with two variations: * **Variation A** * **Variation B** {% hint style="warning" %} The test does not directly modify the recommendation block. It is only used to split traffic and set an assignment cookie. {% endhint %} {% endstep %} {% step %} ### Set the assignment cookie For each variation, AB Tasty sets a specific cookie identifying the assigned group. Example: * Group A → `ab_test_reco_1 = A` * Group B → `ab_test_reco_1 = B` The exact cookie name can be adapted to your technical conventions. This cookie is: * Stored browser-side * Accessible through JavaScript * And allows the website to determine which variation the visitor belongs to {% endstep %} {% endstepper %} ### Client or agency implementation {% stepper %} {% step %} #### Read the cookie The website must read the `ab_test_reco_1` cookie. Example: ``` const variation = getCookie("ab_test_reco_1"); ``` {% endstep %} {% step %} ### Conditional Recommendation & Merchandising API call Depending on the cookie value: * If `variation=A` → call Recommendation Strategy A * If `variation=B` → call Recommendation Strategy B {% endstep %} {% endstepper %} ### Technical considerations - execution timing The experiment assignment cookie must be read: * After the AB Tasty script has been executed * Before triggering the Merch & Recos API ### Notes | AB Tasty Side | Client Side | | ------------------ | -------------------- | | Test creation | Cookie reading | | Traffic allocation | A/B interpretation | | Cookie assignment | Conditional API call | * AB Tasty manages the experimentation layer * The website controls which recommendation strategy is called # How to track performance ## Tracking Setup with Recos Tag The **AB Tasty Tag** lets you both **display recommendations** and **track interactions automatically** — without writing custom tracking code.\ By enriching your HTML with data attributes, events such as *impressions* and *clicks* are automatically detected, enriched, and pushed into the **dataLayer** for use with **Google Tag Manager (GTM)** and **Google Analytics 4 (GA4)**. #### Prerequisite : * **Have AB Tasty tag**. \ To verify that you have successfully installed it on your website, open your console and type ``` recos ``` You should see a global context object if the tag is correctly installed. Else contact your CSM.recos {% stepper %} {% step %} ### Enriching Your HTML for Tracking Once the AB Tasty Tag is installed, enrich your recommendation banners using **data attributes**.\ These attributes allow the tag to detect user interactions and automatically send tracking events to your analytics tool. ### **Enrich your recommendation banner HTML** Add the following **data attributes** to your HTML elements to make the AB Tasty Tag detects them automatically:
AttributePurposeExampleRequired
data-reco-id="[RECO_ID]"Identifies the recommendation container<div data-reco-id="abc123">✅
data-reco-name="[RECO_NAME]"Name of the recommendation <div data-reco-name='Add to cart">✅❌
data-reco-click="[ACTION_ID]"Tracks user interactions (clicks)<a data-reco-click="click_product">✅
data-item-id="[ITEM_ID]"Identifies a specific product in the recommendation<div data-item-id="SKU_123">✅
{% hint style="info" %} The `RECO_ID` corresponds to the ID found in the list of your Recommendations in Recommendations & Merchandising platform. {% endhint %} #### Automatic Event Detection Once implemented, AB Tasty Tag automatically pushes events to the dataLayer or analytic tools: * When an element with `data-reco-id` appears in the DOM → **“show”** event * When an element with `data-reco-click` is clicked → **“click”** event {% hint style="danger" %} If your banner is filled asynchronously, add the `data-reco-id` **only after** the content is fully loaded. {% endhint %} {% embed url="" %} ### Practical example ```html
``` **When the banner appears**, the following event is pushed to the dataLayer: ```js window.dataLayer.push([ "event", "ab_recos_[uuidXX]", { action_id: "show", reco_id: "082ecd63-84ec-4f48-90ce-12271d456020", item_ids: "[\"X23\",\"Y47\"]", debug_mode: true } ]); ``` **When a product is clicked:** ```js window.dataLayer.push([ "event", "ab_recos_[uuidYY]", { action_id: "go_to_page", reco_id: "082ecd63-84ec-4f48-90ce-12271d456020", item_id: "X23", item_ids: "[\"X23\",\"Y47\"]", debug_mode: true } ]); ``` **When “add to cart” is clicked:** ```js window.dataLayer.push([ "event", "ab_recos_[uuidZZ]", { action_id: "add_to_cart_item", reco_id: "082ecd63-84ec-4f48-90ce-12271d456020", item_id: "X23", item_ids: "[\"X23\",\"Y47\"]", debug_mode: true } ]); ``` {% endstep %} {% step %} ### Configuring your analytic tools ### For Google Tag Manager (GTM) Your goal is to configure GTM to send analytics events (GA4) based on AB Tasty Tag events pushed to the dataLayer. #### Step 1: Create a Trigger 1. Go to **Triggers → New** 2. Create a new trigger: * **Name:** `Recos - trigger` * **Trigger type:** Custom Event * **Event name:** `ab_recos` * Check **Use regex matching** * Choose **All Custom Events** 3. Save. #### Step 2: Create the Data Layer Variables Go to **Variables → User-defined variables → New**, and create the following variables: | Variable Name | Data Layer Variable | Type | | ------------- | ------------------- | ------------------- | | `action_id` | `recos.action_id` | Data Layer Variable | | `reco_id` | `recos.reco_id` | Data Layer Variable | | `reco_name` | `recos.reco_name` | Data Layer Variable | | `item_id` | `recos.item_id` | Data Layer Variable | | `item_ids` | `recos.item_ids` | Data Layer Variable | | `debug_mode` | `recos.debug_mode` | Data Layer Variable | #### Step 3: Create the GA4 Event Tag 1. Go to **Tags → New** 2. Configure: * **Tag name:** `Recos - Event GA4 - recos` * **Tag type:** GA4 Event * **Measurement ID:** (found in the client’s GA4 → Admin → Data Stream) * **Event name:** `ABTastyRecos` 3. Add all six event parameters using the variables created above: | Event Parameter | Value | | --------------- | ---------------- | | `action_id` | `{{action_id}}` | | `reco_id` | `{{reco_id}}` | | `reco_name` | `{{reco_name}}` | | `item_id` | `{{item_id}}` | | `item_ids` | `{{item_ids}}` | | `debug_mode` | `{{debug_mode}}` | 4. Select the **Recos - trigger** created earlier. 5. Save your workspace. You should now have **8 workspace changes**:\ → 6 variables + 1 trigger + 1 tag. #### Step 4: Test the Setup **Connect Tag Assistant** 1. Go to **Tag Assistant** in GTM. 2. Enter the URL of your site. 3. Click **Continue** to launch the preview mode. **Validate in GA4** Go to **GA4 → Admin → DebugView** and confirm that the following appear: * Event: `ab_recos` * Parameters: `action_id`, `reco_id`, `item_ids`, etc. **Example** When a recommendation appears: * Event: `ab_recos` * `action_id`: `show` * `item_ids`: all displayed products * `reco_id`: ID of the recommendation When a product card is clicked: * Event: `ab_recos` * `action_id`: `go_to_page` {% endstep %} {% step %} ### Retrieving Products from a RECO\_ID You can also retrieve recommendation data programmatically through the Recos Tag. #### Example ```javascript recos.reco(RECO_ID).then(console.log); ``` This returns a JSON list of products: ```json [ { "id": "id1", "title": "title 1", "price": 20, "strike_price": 40, "discount_rate": 50, "img_link": "https://image.png", "link": "https://link1" }, { "id": "id2", "title": "title 2", "price": 30, "strike_price": null, "discount_rate": 0, "img_link": "https://image.png", "link": "https://link2" } ] ``` You can also retrieve any variable’s value directly: ```javascript recos.variable(VARIABLE_NAME).then(console.log); ``` *** **Your tracking setup is now complete.**\ Your recommendation impressions, clicks, and conversions will now flow automatically into your analytics tool through GTM. #### How to follow performance ? Once your AB Tasty Tag and analytics integration are live, you can monitor performance directly in the **Reports** section of your AB Tasty dashboard. **1. Access your performance reports** * Go to your AB Tasty **Recommendations & Merchandising** dashboard. * Click **Reports** in the left sidebar. * Select the **Experience** you want to analyze. **2. Key metrics available** | Metric | Description | | ------------------------- | ------------------------------------------------------------------------------ | | **User rate** | % of visitors interacting with recommendations. Measures visibility and reach. | | **Weight in revenue** | % of total revenue driven by users exposed to recommendations. | | **Revenue / user impact** | Average uplift in spend for users who engage with recommendations. | **3. Performance over time** Use the **Evolution** graph to track how impressions, clicks, and revenue evolve.\ You can filter by **date range**, **device**, or **experience** to isolate trends. **4. Optimization tips** * Compare multiple experiences to identify high-performing ones. * Monitor underperforming campaigns to find relevance or display issues. * Establish a regular review schedule (weekly or monthly). → Learn more in [**Analyzing Performance Reports**](/recommendations-and-merchandising/getting-started/recommendations/reporting-recommendation) {% endstep %} {% endstepper %} # Merchandising # Create a merchandising strategy A **Merchandising** strategy controls product ordering *within categories and collections* to enforce business priorities, best sellers first, promotions surfaced, slow movers pushed down, without manual back-office sorting. Commerce computes a score per product per strategy and syncs those scores to your CMS or search engine, which reorders the catalog accordingly. {% hint style="info" %} **What changed:** Merchandising comes from the former **Recommendations & Merchandising** product. The builder now shares the same shell as Recommendations (**New Rule**, **Pins**, **Global customization**, **Save / Save and deploy**) and adds **Pins for category** for per-category pinning. Under the hood each strategy still carries a `MERCH_ID` used for deployment to the CMS or search engine. {% endhint %} ### How merchandising works Merchandising does not reorder products live on every request. Instead: 1. **Score generation**: Commerce computes a merchandising score per product, per strategy, from the strategy's rules (best sellers, new arrivals, margin, and so on). 2. **API sync**: those scores are transmitted to your CMS or search engine. 3. **Catalog update**: the CMS reorders products using the scores. 4. **Front-end display**: the reordered list is shown to visitors. {% hint style="warning" %} **Filters only hide products, they don't change AB Tasty's ranking.** A filter on your website removes products from view, but the underlying score-based ordering is unchanged. If products reorder unexpectedly, check your filter logic first. Because scores are computed and synced (not recalculated on every request), rankings stay stable between syncs. {% endhint %} ### Creating a merchandising strategy {% stepper %} {% step %} #### **Click Create merchandising +**
The **New merchandising strategy → Pick a strategy to start from…** modal opens with a starting point such as **Basics → Empty strategy**. {% endstep %} {% step %} ### Build the strategy
The right-hand **Your strategy results** panel previews the ordered products *for a selected category context*. Until you pick a category, or if your configuration returns nothing for it, the panel shows an empty state such as **"0 results returned for \[Category: None]"** / "Your current configuration doesn't return any products for the context you are trying to preview…". Choose a category to see how that category would be ordered. {% endstep %} {% step %} ### Save and Deploy Merchandising uses the two-step **Save** / **Save and deploy** model shared by all strategies. **Save** stores a draft; **Save and deploy** computes the product scores and syncs them to your CMS or search engine so the catalog reorders. {% endstep %} {% endstepper %} Selecting a starting point opens the builder at `/merchandising/new/builder`. ## The Merchandising builder The header follows the shared pattern, editable strategy name, a **Draft** badge, **Save**, and **Save and deploy**. The configuration panel contains: #### Default rule A new merchandising strategy opens with a **Default** rule already in place: > Products sorted by `revenues_last_30_days`, **Unlimited** This sorts the category by 30-day revenue with no result cap. Add more rules with **New Rule +** to layer additional sources or refinements on top. #### Pins for category **Pins for category** lets you pin products *per category*. Choose a category in the **Select…** category selector, then *"Pin product(s) for a specific category"*, the pinned products are forced to the top of that category only. This is what makes merchandising category-aware: different categories can have different pinned products under the same strategy. #### Pins **Pins → Pin product(s)** pins products across the strategy, independent of category. {% hint style="info" %} A **Pin** forces products to the top within this strategy. To promote or demote products *globally across all strategies*, use the dedicated [Boost & Bury](https://file+.vscode-resource.vscode-cdn.net/Users/didier/repos/abtasty/commerce/docs/commerce/03-creating-rules-boost-and-bury/) rules instead. {% endhint %} #### Global customization **Global customization → New global customization (filter, exclude, sort…)** adds rules that apply across the strategy, **Filter**, **Exclude**, **Diversification**, **Shuffle**, **Sort by…**, or **Filter if…**. (Remember the warning above: filters hide products, they do not change the score-based ranking.) ## The Merchandising list
The toolbar offers **Create merchandising +**, **Group By**, **Filters**, **Display settings**, and a search box. The table columns: | Column | Meaning | | ---------------------- | ------------------------------------------------------------------------------------------- | | **Merchandising name** | The strategy's name. | | **Status** | **Deployed**, or **Deployed (Draft Waiting…)** when a live version has saved edits pending. | | **Categories** | The categories the strategy covers (for example "11 categories", "sport"). | | **% of revenue** | Share of revenue attributed to the strategy. | | **CTR** | Click-through rate. | | **Conv. Rate** | Conversion rate. | | **Tag(s)** | Labels applied to the strategy. | | **Creator** | Who created it. | | **Creation** | Creation date and time. | # How to integrate Merchandising via API This guide explains how to fetch product strategies from AB Tasty's merchandising API and display them on your website. ### Overview The Merchandising feature surfaces curated product lists (strategies) configured in the AB Tasty back-office. Two endpoints are exposed depending on what you already know about the strategy: * **By category ID** — when your front-end only knows the current category, hit the category endpoint and the API resolves the bound strategy for you. * **By strategy UUID** — when the UUID is already known (cached, configured, etc.), call the UUID endpoint directly. Both endpoints return the same payload shape (items, facets, pagination) and accept the same query parameters. Base URL: `https://uc-info.eu.abtasty.com/v1/reco/v1` > **`v1` appears twice, and both are required.** The first belongs to the AB Tasty gateway, the second selects version 1 of the Merchandising API. > > A URL built with a single `v1` (`https://uc-info.eu.abtasty.com/v1/reco/{site_id}/...`) reaches a deprecated internal endpoint. It answers `200` too, so the mistake produces no error — only wrong results: > > `facets` and `filters[]` behave the same on both. | | Single `v1` (deprecated) | Double `v1` (this guide) | | ------------------------ | ---------------------------------- | ------------------------------------ | | `merch/category_id/{id}` | returns a strategy UUID | returns products | | `sort[field]` | silently ignored, results unsorted | applied, or `400 INVALID_SORT_FIELD` | | `limit` omitted | returns the **entire** list | returns 20 items | | `limit=0` | `422` | no limit | *** ### Authentication All requests require a JWT in the `Authorization` header: ``` Authorization: Bearer ``` *** ### Endpoints #### 1. Fetch items by category ID ``` GET /{site_id}/merch/category_id/{category_id} ``` Resolves the merchandising strategy bound to `category_id` and returns its ranked products in a single call. Use this endpoint when your front-end knows the category it is rendering but not which strategy is deployed on it. The binding lives in the AB Tasty back-office, so merchandisers can change the strategy on a category without a front-end release. The `category_id` in the path also scopes the products returned — you do **not** need to repeat it in `variables`. **Path parameters** | Parameter | Type | Description | | ------------- | ------- | ----------------------------- | | `site_id` | integer | Your AB Tasty site identifier | | `category_id` | string | The category identifier | Query parameters, response payload and error codes are identical to the by-UUID endpoint, with one extra error: | Status | Error code | Reason | | ------ | ------------------ | ------------------------------------------------------------- | | 400 | `UNKNOWN_CATEGORY` | No strategy is bound to this `category_id` for this `site_id` | *** #### 2. Fetch items by strategy UUID ``` GET /{site_id}/merch/{merch_id} ``` Returns the ranked list of products for a given strategy, with optional filtering, faceting and pagination. Use this endpoint when the strategy UUID is already known. > **This endpoint needs the category in `variables`.** A strategy can be deployed on several categories, so its UUID alone does not say which products to rank. Without `variables={"category_id":"…"}` the response is a valid `200` with an **empty** `items` array. See Scoping a strategy to a category. **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` | JSON | — | JSON object injected into the strategy template. Required in practice on the UUID endpoint — see Scoping a strategy to a category. Ex: `variables={"category_id":"1439"}` | | `fields` | JSON array | — | JSON array of product fields to return. Ex: `["id","title","price"]`. `id` is always included. | | `page` | integer | `null` | 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. **Defaults to `20` when omitted.** Use `0` for no limit. | | `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. | | `sort[f]` | string | — | Override the strategy's ordering. `f` is the field name, value is `asc` or `desc` (case-insensitive). See sort syntax below. | | `output_format` | string | `json` | Response format. Accepted values: `json`, `csv`, `proximis`. | | `delimiter` | string | `;` | CSV delimiter (only used when `output_format=csv`). Accepted values: `,`, `;`, `%09`, \` | These query parameters apply to **both endpoints** (UUID and category). **Scoping a strategy to a category** Merchandising strategies rank the products of **one category**. The category is supplied through the `category_id` variable: ``` ?variables={"category_id":"1439"} ``` * **Category endpoint** — supplied automatically from the path. Pass `variables` only to override it. * **UUID endpoint** — you must supply it yourself. A strategy can be deployed on several categories, so the UUID does not imply one. When the category is missing, the strategy matches no products and the response is a valid `200` with an empty `items` array and `total_items: 0` — not an error. An empty result on the UUID endpoint is almost always a missing `category_id`. > The variable is named `category_id` by default, but it is configurable per site. If your strategies were set up with a different name, use that one — your AB Tasty contact can confirm which applies to your site. **Filter syntax** Filters use PHP-style bracket notation. Two syntaxes are supported depending 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[field][]=value` for equality. Repeat the parameter on the same field 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 ``` **Sort syntax** The `sort[field]=direction` parameter **replaces the strategy's own ordering** (pins included). The strategy's catalog and your active `filters[...]` still apply. ``` ?sort[price]=desc ?sort[created_at]=asc ``` * Only **one** sort field per request. * Direction is `asc` or `desc`, case-insensitive. * The field must be flagged **`merch_sortable`** for your site in the AB Tasty back-office (this is a dedicated flag, distinct from the internal `sortable` flag). Requesting an unmarked field returns `400 INVALID_SORT_FIELD`. **Sort-specific error codes** (all returned as `400 Bad Request`) | Error code | Reason | | ------------------------ | ------------------------------------------------------ | | `INVALID_SORT_SYNTAX` | Malformed `sort[...]` key, or more than one sort entry | | `INVALID_SORT_FIELD` | Field is not sortable for this site | | `INVALID_SORT_DIRECTION` | Direction is not `asc` / `desc` | | `SORT_UNSUPPORTED` | The strategy does not support runtime sorting | **Response (JSON)** ```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 Pick one of the two entry points depending on what your front-end has on hand. **A. You only know the category ID** — single call, the category scopes the products: ``` GET /{site_id}/merch/category_id/1439?fields=["id","title","price"]&limit=20&facets=true → items[], facets{}, total_items, total_pages ``` **B. You already have the strategy UUID** — single call, pass the category in `variables`: ``` GET /{site_id}/merch/{uuid}?variables={"category_id":"1439"}&fields=["id","title","price"]&limit=20&facets=true → items[], facets{}, total_items, total_pages ``` Query-string values containing JSON or brackets must be URL-encoded. **Then, for both:** ``` 1. Display facets and let the user apply filters GET ...&filters[category][]=shoes&filters[available][]=1 → filtered items[] and updated facets{} 2. Paginate GET ...&page=2 — or — GET ...&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. * **`limit` defaults to `20` when omitted.** Pass `limit=0` to return all matching items with no pagination cap. * Facet computation adds overhead — only request `facets=true` when you need to render facet counts. * **Per-field opt-in is required in the AB Tasty back-office:** * `filters` and `facets` only accept fields flagged as **`facetable`**. * `sort` only accepts fields flagged as **`merch_sortable`** (distinct from the internal `sortable` flag — they are not interchangeable). Requesting a non-opted-in field returns `400`. * Two situations look similar but are distinct: * **No strategy bound to the category** → `400 UNKNOWN_CATEGORY` (never a `200` with an empty payload). * **Strategy found but no category supplied** (UUID endpoint without `variables`) → `200` with an empty `items` array. # How Merchandising Works Each merchandising strategy creates a **ranked list of products** based on rules and algorithms (bestsellers, new arrivals, margin, etc.). **Key principles** * Every strategy has a unique **MERCH\_ID**. * **Scores** are automatically computed and synchronized via API. * Your **CMS consumes these scores** to reorder products in its catalog. * **Filters** on your website only hide products — they **don’t change AB Tasty’s ranking**. **Data flow overview** 1. **Score generation** – AB Tasty calculates a merchandising score per product and strategy. 2. **API sync** – Scores are sent to your CMS or search engine. 3. **Catalog update** – The CMS reorders products using these scores. 4. **Front-end display** – The ordered list is shown on your website; filters simply hide non-matching items. **Integration logic**\ Your CMS retrieves scores via API:\ `GET https://api.abtasty.com/reco/` → returns product SKUs with their scores. The CMS then applies these scores as a **sorting layer**. AB Tasty doesn’t recalculate dynamically, ensuring **stable performance**. **Sync frequency** * Scheduled (daily/hourly) or manual # How to enable Merchandising Reporting Merchandising reporting lets you track the performance of your strategies (views, clicks, conversions) directly in Google Analytics 4 (GA4).\ To do this, you just need to make sure that Merch events are sent to your website’s DataLayer through the AB Tasty tag. ### Enabling Merchandising reporting {% stepper %} {% step %} #### Check that the AB Tasty tag is installed If you already have product recommendations running on your site, the tag is already there. There is no need for extra setup. {% endstep %} {% step %} #### Configure analytics in your tag Your **Technical Support Engineer (TSE)** or internal tech team simply needs to add this key to the `config.json` file of your tag configuration: 
"analytics": {
  "merchandisingEventsToDataLayer": ["site"]
}
{% hint style="info" %} This automatically enables Merchandising events (`show`, `click`, `add_to_cart`, `convert`) to be pushed into your site’s DataLayer exactly like Recommendation events. {% endhint %} {% endstep %} {% step %} #### Make sure GA4 / GTM is set up If your Recommendation reporting is already configured, Merch events will be captured the same way once the additional variables **`event_id`** and **`category_id`** are included. Otherwise, your TSE or internal tech team can follow the existing Recos GTM setup (same trigger, variables, and event structure) and add these two variables. {% endstep %} {% step %} #### Test it Open your site → open the browser console → type `dataLayer`.\ You should see events like: ``` { "event": "ab_recos_xxxx", "recos": { "action_id": "show", "reco_id": "xxxx", "item_ids": "[\"12345\",\"67890\"]" } } ``` {% hint style="info" %} If you see them, it means Merch events are being correctly sent to GA4. {% endhint %} {% endstep %} {% endstepper %} If you want to know more about the **Merchandising strategy reporting** **dashboard** with metrics like views, clicks, conversion rate, and top products, read [Merchandising Reporting](/recommendations-and-merchandising/getting-started/merchandising/merchandising-reporting) {% hint style="info" %} **Need help?** Contact your **Technical Success Engineer (TSE)** to confirm or validate the configuration. {% endhint %} ### How to setup HTML on your website ? To allow the AB Tasty tag to detect and send Merch events automatically, your merchandising banners must include specific HTML attributes. If AB Tasty does not manage your frontend (custom site or CMS), your development team must add these attributes directly in the HTML of your merchandising banners.\ Each product container should include these attributes so the AB Tasty tag can detect and send events. ### Required attributes | Attribute | Description | Example | | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | `data-category-id` | Category identifier | `
` | | `data-merch-uuid` *(only mandatory for Merch deployed by API)* |

Strategy merch identifier

(Both data-merch-uuid and data-category-id need to be on the same HTML element)

| `
` | | `data-item-id` | Product identifier | `
` | | `data-reco-click` | User interaction type | `