API Documentation
Cross-sell carousel API
Reference details for the carousel service that orchestrates complementary product recommendations based on category context, merchandising rules, and optional variant expansion.
What is this?
A lightweight API layer that builds cross-sell carousels for PLP and category pages by translating a category or product context into a curated set of complementary items. It can inject personalization signals, merchandising rules, and variant expansion without replacing the existing commerce stack.
What it enables
- Contextual cross-sell blocks like “goes well with” or “pair it with.”
- Personalized carousel slots based on shopper context and category intent.
- Variant-aware outputs to surface size, color, or pack options.
- Reusable JSON payloads for web, app, and email placements.
Endpoint
https://n8n.salnl.net/webhook/d610e07b-b964-4fda-99e5-1afea4ad25ff?category=milk&limit=4&expand_variants=true&cross_variants_limit=3
User: test
Password: Test123
Build process
How we created it
Input normalization
- Normalized category names and product metadata for consistent matching.
- Mapped category context to curated cross-sell clusters and rules.
Carousel assembly
- Scored complementary products using similarity and merchandising signals.
- Expanded variants to surface size, flavor, or package alternatives when requested.
Query-to-carousel pipeline (n8n-orchestrated)
- API endpoint ingests category or product context.
- Context enrichment and rule-based cross-sell matching.
- Candidate retrieval from the product catalog.
- Optional variant expansion and filtering.
- JSON response with carousel-ready cards.
Request details
Query parameters
This endpoint builds a carousel based on category context and optionally expands variants to provide more choice per cross-sell slot.
- category (string, required)
- The category or product context used to infer complementary items. Example:
category=milk - limit (integer, optional)
- Maximum number of carousel items to return. Example:
limit=4 - expand_variants (boolean, optional)
- Controls whether variant items are included for each cross-sell result. Example:
expand_variants=true - cross_variants_limit (integer, optional)
- Maximum number of variants to return per cross-sell item. Example:
cross_variants_limit=3
Applications
Example use cases
- PLP and category cross-sell modules for basket building.
- Complementary product suggestions on PDPs and cart drawers.
- Bundle assembly for meal kits, party packs, or seasonal sets.
- Personalized merchandising placements across channels.
- Campaign-specific cross-sell carousels for promotions.