Discovery API - Integration guidelines for Product Listing Pages ranking

• Goal: Apply Sensefuel’s AI product ranking to your PLPs (including Showcase feature).
• Out of scope: Hyper‑personalization, facets (filters), user sorting.
• Benefit: Strong product ranking relevance + business control with a minimal integration impact.

Endpoints

• Use: /navigation
• Why: Returns ranked products for a PLP (by scope_id or product_type), plus optional Showcase module.
• For other ranking needs you can use in our Discovery API other endpoints such as landing_page or selection, etc.  with the same principles.

Key Decisions before starting your project

• Retrieving model for the /navigation endpoint: 
  • Choose one or both depending on your needs. These attributes are data propagated to Sensefuel from your catalog feed as a CSV/XML file or through our Catalog API. 
    • scope_id (category identifier),
    • product_type (single classification per product).
• Feed rules:
  • Each product has most of the time one product_type.
  • Each product may have multiple scope_id values, semicolon‑separated without spaces\ e.g., CAT12345;CAT78910;CAT59595.

Request Pattern

• New random user_id and track_id per job run (series of API call to retrieve all your PLPs ranking).
  Why randomizing ? user_id and track_id are used to hyper personalize the PLP ranking which is not corresponding to this implementation context here (retrieving a PLP ranking and display the same ranking for all users). 
• Pagination: limit ≤ 100; loop offset (0, 100, 200, …) until complete or you reach your cap.
• Modules: Request only what you need, typically:
  • items (ranked products, generally with the addition of "fields" and "variants_fields" with only the ["id"] to obtain in the API response),
  • showcases (business rules configured in the platform, generally with the addition of "fields" and "variants_fields" with only the ["id"] to obtain in the API response),
  • tracking (mandatory; helps avoid duplicates / manage cursors).

Example (illustrative):

Request

curl --location 'https://api.sensefuel.live/discovery/your_unique_environment_identifer/navigation' \
--header 'x-api-key: your_discovery_api_key' \
--header 'Content-Type: application/json' \
--data '{
    "query" : {
        "search_scope" : {
            "scope_id" : "your_category_id"
        },
        "user_id": "GUID_to_randomized",
        "track_id": "GUID_to_randomized"
    },
    "modules": {
        "items": {
            "from": 0,
            "size": 100,
            "fields" : ["g:id"],
            "variants_fields" : ["g:id"]
        },
        "showcases" :{
            "fields" : ["g:id"],
            "variants_fields" : ["g:id"]
        },
        "tracking": {}
    }
}'

Assembly Rules (PLP output)

Showcase first: Display products from showcases.items before ranked items, preserving returned order.

For your information find below the showcase templates and parameters provided in our API responses (this rendering information is optional to reduce integration effort):

• MANUAL_RANKING → neutral (showcased products are not explicitly presented to your customers) 
• FULL_PRODUCT → sponsored (showcased products are explicitly presented to you customers with a background color and title)
• BANNER → visual (showcased products are explicitly presented to your customers with a visual next to the 1st product)

Scheduling & Caching

• Recommended refresh:  4–6 times per day for all navigable PLPs in order to retrieve and display fresh ranking and take into account eventual business rules configured in Sensefuel's platform. However, once per day can be enough, just make sure it aligns with business users needs. 
• Store results: Cache per‑PLP lists. Front‑end reads these lists without refactor.

Resilience & Monitoring (essentials)

• Retries: Set up automatic retries; use last successful cache on failure.
• Observability: Log API calls sessions, PLP request counts, item counts per PLP and total items counts, as well as errors.