Unified Discovery API - Integration guidelines for Product Listing Pages ranking

Goal

This integration pattern allows merchants to leverage Sensefuel's AI-powered ranking and Showcase merchandising capabilities on Product Listing Pages (PLPs) while keeping the existing front-end architecture largely unchanged.

Unlike a real-time integration, rankings are shared across all users and refreshed through a controlled caching strategy. This approach delivers the benefits of Sensefuel's ranking engine with minimal implementation effort and infrastructure impact.

Out of Scope

This integration pattern is not designed for:

• Hyper-personalized ranking
• User-specific recommendations
• Dynamic filters and facets
• Autocomplete
• Real-time behavioral adaptation

The objective is to provide high-quality product ranking and merchandising while maintaining a predictable and cacheable experience.

Defining the PLP Context

The Unified Discovery API can retrieve products for a PLP using either a scope_id or a product_type.

Option 1: scope_id

This is the recommended approach when the e-commerce platform already relies on category identifiers.

A scope_id corresponds to a category context propagated to Sensefuel through the catalog feed.

A product can belong to multiple categories and therefore multiple scope_id values.

Example: CAT12345;CAT78910;CAT59595

Option 2: product_type

This approach is recommended when navigation relies on a hierarchical product taxonomy.

Examples:

Women
Women > Shoes
Women > Shoes > Sneakers

A PLP can therefore be requested at any level of the hierarchy.

The choice between scope_id and product_type should be aligned with the website's navigation model.

Business Context

Some projects require rankings to be generated at the store level, business context level.

This is typically the case when business data such as:

• Product availability
• Merchandising rules (segments)

are managed per business context.

In these situations, the store_code parameter should be provided so that Sensefuel can retrieve products and offers matching the correct store context.

For example:

and

must be considered as different ranking contexts.

As a result, rankings should be cached independently for each (scope_id, store_code) combination.

Relevance and Personalization

This integration pattern intentionally avoids user-level personalization.

The Unified Discovery API does not require a user_id and this parameter should not be used for this type of implementation.

Instead, a new random session_id should be generated whenever a ranking is refreshed and sent through the x-session-id request header.

Using a randomized session identifier ensures that rankings remain generic and reusable for all users while still benefiting from Sensefuel's relevance model, merchandising rules, and ranking optimizations.

Request Optimization

For ranking-only integrations, it is recommended to retrieve only the attributes required by the consuming application.

The Unified Discovery API allows clients to control the returned attributes through the fields parameter.

In most implementations, only a product identifier is required.

Common examples include:

• id
• item_group_id
• productId
• EAN
• GTIN

Example:

GET /listing/products?scope_id=CAT12345&fields=id

or

GET /listing/products?scope_id=CAT12345&fields=item_group_id

Reducing the number of returned attributes:

• Minimizes payload size
• Improves response times
• Reduces cache storage requirements
• Simplifies downstream processing

Any indexed catalog attribute can be requested if needed.

API Usage

Rankings should be retrieved using the Unified Discovery API Listing endpoint.

Typical request:

GET /listing/products?scope_id=CAT12345&from=0&size=100

or

GET /listing/products?scope_name=Women%20%3E%20Shoes%20%3E%20Sneakers&from=0&size=100&include=showcases

Only request the data strictly required by the integration.

Pagination

Products should be retrieved in batches of maximum 100.

Example:

Continue until all products have been retrieved or until the desired limit has been reached.

Caching Strategy

In this integration context Sensefuel should not be called for every PLP page view.

Instead, rankings should be cached and refreshed according to a predefined TTL (Time-To-Live).

Recommended Flow

1. A visitor accesses a PLP.
2. The application checks whether a valid ranking exists in cache.
3. If a valid cache entry exists, the cached ranking is served.
4. If the cache has expired, the application requests a fresh ranking from the Unified Discovery API.
5. The ranking is stored in cache and subsequently served to all visitors until the next expiration.

This strategy provides a good balance between ranking freshness and infrastructure efficiency.

Cache Duration

The cache duration should be defined jointly with business teams.

Key considerations include:

• Catalog update frequency
• Inventory updates
• Price updates
• Showcase configuration activity
• Business expectations regarding freshness

Typical cache durations range from a few hours to one day.

Manual Refresh

In addition to automatic expiration, a manual refresh mechanism is strongly recommended.

This allows business teams to immediately apply:

• Showcase modifications
• Merchandising updates
• New campaigns
• Catalog corrections
• Strategic ranking adjustments

without waiting for the cache to expire.

Showcase Handling

Showcase data should be requested alongside product rankings.

GET /listing/products?...&include=showcases

Showcases should be rendered according to the order returned by the API and integrated into the PLP experience according to the business configuration defined within the Sensefuel platform.

Because Showcases are configured dynamically by business users, regular cache refreshes ensure that storefront merchandising remains up to date.

Resilience

If a ranking refresh operation fails, the application should continue serving the most recent successful cache entry.

Automatic retry mechanisms should also be implemented to mitigate temporary API or network failures.

This approach guarantees a stable storefront experience while maintaining merchandising continuity.

Monitoring

At minimum, the following indicators should be monitored:

• API response status codes
• Ranking refresh duration
• Number of PLPs refreshed
• Number of products retrieved per PLP
• Showcase retrieval success rate
• Cache hit ratio
• Cache refresh failures

These metrics help quickly identify catalog, merchandising, operational, or integration issues.