Search
The Search module provides product discovery for storefront-facing applications. It supports keyword search, faceted filters, autocomplete suggestions, product listing pages backed by Vertex AI retail search, display banner ads, and product recommendations.
Product recommendation operations — placement-based (GET) and unified strategy router (POST).
Operations
GET
# Placement-based product recommendations.
POST
# Unified recommendation strategies.
FDK Method Name: getRecommendations
Returns placement-based product recommendations for a storefront visitor. The backend (Vertex Predict or RRA) is determined per placement_type via the PLACEMENT_BACKEND_* environment variables — no global feature flag. Returns a single flat product list. Always returns HTTP 200 — failures degrade to an empty items array with metadata.fallback=true.
Parameters
placement_type
string
Required
Recommendation placement key that determines the model to invoke (e.g. similar-products, recently-viewed, bought-together).
visitor_id
string
Required
Storefront visitor ID. Used by Vertex for personalisation context and by RRA for session scoping.
product_id
string
Single seed product ID. Mutually exclusive with product_ids.
product_ids
string
Comma-separated seed product IDs. Mutually exclusive with product_id. Results are merged into a single flat list.
page_size
integer
Number of recommended products to return (max 50).
Default Value : 10
filter
string
Vertex filter expression to narrow recommendation results.
pincode
string
Delivery pincode for price zone resolution.
Response
200
400
Success. Returns a flat list of recommended products. Empty items array on fallback (circuit open, timeout, or no results).
RecommendationListing
items
array of object (RecommendedProductItem)
Flat list of recommended products. Empty array on fallback.
Array of RecommendedProductItem
uid
integer
Unique product identifier.
name
string
Product display name.
slug
string
URL-safe product identifier.
brand
object
Brand name and UID.
price
object
Effective and marked price bands.
medias
array of object
Product images.
sellable
boolean
Whether the product is currently purchasable.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
page
object (StandardPage)
StandardPage
current
integer
Current page number (1-indexed).
total
integer
Nullable
Total number of pages. null for cursor-based (open-ended) endpoints.
has_previous
boolean
Whether a previous page exists.
has_next
boolean
Whether a next page exists.
item_total
integer
Total number of items on the current page.
type
string
Pagination mode.
Enum
next_id
string
Cursor token for the next page. Only present when type=cursor and has_next=true.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
metadata
object (RecommendationListingMetadata)
RecommendationListingMetadata
placement_type
string
Echoes the requested placement_type.
attribution_token
string
Vertex attribution token for downstream event logging. Empty string when RRA backend is active.
missing_ids
array of string
Seed product IDs that were not found in productMaster.
fallback
boolean
Present and true only when a fallback response is returned.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
Examples
Parameters
Parameters are not required.
Was this section helpful?
GET
Response
Placement-based product recommendations.
getRecommendations
FDK Method Name: postRecommendations
Single entry point for all recommendation strategies: batch, widget, personalized, curated, filters, and trends. Use the `strategy` field to select the recommendation type. If `strategy` is omitted but a `products` array is present, auto-detects as batch. Always returns HTTP 200.
**Strategy summary:**
- **batch** — Similar products for one or more seed product IDs (via RRA).
- **widget** — Widget-based recommendations (via RRA); requires widget_id + widget_type + store.
- **personalized** — Personalized category recommendations blending exploit + coldstart + explore buckets.
- **curated** — Editorial / curated content widgets from RRA; requires widget_id + widget_level + store.
- **filters** — Per-user filter affinities (brand, category, discount); requires user_id + store.
- **trends** — Top trending option codes by Cohort, Segment, or Brick; requires trend_type + value + store.
Parameters
No Parameters
Request body
strategy
string
Recommendation strategy. If omitted and `products` is present, defaults to batch.
Enum
products
array of object (SimilarBatchProduct)
Seed product entries (strategy=batch). At least one entry with product_id is required.
Array of SimilarBatchProduct
product_id
string
Required
Seed product ID.
store
string
Store / channel key for RRA routing. Defaults to the application ID when omitted.
size
integer
Max number of similar products for this seed. Defaults to RRA_MAX_PER_PRODUCT server config.
pincode
string
Delivery pincode for price zone resolution (batch/widget/personalized).
widget_id
string
Widget placement identifier (strategy=widget, curated).
widget_type
string
Widget type key (strategy=widget).
store
string
Store / channel key. Required for widget, personalized, curated, filters, and trends strategies. Falls back to x-store-id header.
page_size
integer
Number of products to return, max 50 (strategy=widget/personalized).
Default Value : 20
show_default_if_no_data
boolean
Return default content if none exists (strategy=widget, curated).
Default Value : false
primary_cohort
string
Primary cohort tag (strategy=personalized).
category_id
string
Category identifier (strategy=personalized).
offset
string
Opaque cursor token for pagination (strategy=personalized).
widget_level
string
Widget level / tier identifier (strategy=curated). Required when strategy is curated.
user_id
string
User identifier for fetching per-user filter affinities (strategy=filters). Required when strategy is filters.
trend_type
string
Trend dimension type (strategy=trends). Required when strategy is trends.
Enum
value
string
Trend dimension value to query (strategy=trends). Required when strategy is trends.
Response
200
400
Success. Response shape depends on strategy — batch returns SimilarBatchListing, widget returns WidgetListing, personalized returns PersonalizedListing, curated returns CuratedListing, filters returns UserFiltersResult, trends returns TrendsResult. Empty items/data on fallback.
Examples
Parameters
body:
body
Was this section helpful?
POST
Response
Unified recommendation strategies.
postRecommendations
Operations
GET
# Lists all products.
GET
# Browse products belonging to a collection.
GET
# Get filter configuration.
GET
# Visual image-based product search.
GET
# Retrieves search result listings.
FDK Method Name: getProducts
List all products available in the catalog. Supports filtering based on product name, brand, department, category, collection, and more, with sorting options based on price, ratings, discounts, and other criteria.
**Sponsored product injection:** When Osmos PLA ads are available, sponsored products are injected into the items array at configurable intervals (default: positions 4, 7, 10, 13 — 1-indexed). Sponsored items carry `sponsored: true` and a `ad_meta` tracking block alongside all standard product fields. Organic and sponsored products are otherwise identical in shape — clients must check `sponsored` to distinguish them.
Parameters
q
string
The search query for entering partial or full name of product, brand, category, or collection.
f
string
The search filter parameters. Filter parameters will be passed in f parameter as shown in the example below. Double Pipe (||) denotes the OR condition, whereas Triple-colon (:::) indicates a new filter parameter applied as an AND condition.
filters
boolean
True for fetching all filter parameters and False for disabling the filter parameters.
Default Value : true
sort_on
string
The order in which the list of products should be sorted, e.g. popularity, price, latest and discount, in either ascending or descending order. See the supported values below.
Enum
page_id
string
Page ID to retrieve next set of results.
page_size
integer
The number of items to retrieve in each page.
Default Value : 12
page_no
integer
The page number to navigate through the given set of results.
Default Value : 1
page_type
string
Available pagination types are cursor or number.
Default Value : cursor
Enum
store_ids
string
Comma-separated store / channel IDs (e.g. "AJIO,AJIO_INTL")
more_filter_categories
string
Comma-separated list of category slugs whose category-specific "More Filters" should be included in the response filters array. Each matching filter carries `is_more_filter: true` and `category_slug` so the UI can render them in a separate section. Max 3 slugs are evaluated per request.
Response
200
Success. Returns a paginated list of products.
SearchProductListing
items
array of object (SearchProductItem)
Paginated list of organic and sponsored product items.
Array of SearchProductItem
uid
integer
Unique product identifier.
name
string
Product display name.
slug
string
URL-safe product identifier.
item_type
string
Always "standard" for PRIMARY-type catalog.
sellable
boolean
Whether the product is currently purchasable.
discount
string
Formatted discount string (e.g. "20% OFF"). Empty string when no discount.
brand
object
Brand name, uid, logo, and navigation action.
price
object
Price object with effective, marked, and selling legs. Each leg has min/max/currency_code/currency_symbol.
medias
array of object
Product images (type=image, url).
action
object
Navigation action for deep-linking to the product detail page.
_custom_json
object
Arbitrary key-value metadata from the catalog.
tags
array of string
Product tags from the catalog (e.g. "Single", "Mass"). Empty array when no tags are present.
sponsored
boolean
Present and true only for Osmos PLA sponsored products injected into the listing. Absent on organic products.
ad_meta
object (AdMeta)
AdMeta
uclid
string
Unique click link ID for Osmos impression/click tracking.
mcid
string
Merchant click ID.
sclid
string
Search click link ID.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
primary_urgency_tag
object (UrgencyTag)
Nullable
Highest-priority urgency tag for this product, resolved by the tag engine at search time. Present only when TAG_ENGINE_ENABLED=true and the tag engine returns a tag for this product. null when no urgency tag applies.
UrgencyTag
tag_name
string
Internal tag identifier used for filtering and analytics.
short_text
string
Display label shown on the product card badge.
icon_url
string
CDN URL of the badge icon to render on the product card.
position
string
Nullable
Tag placement position returned by the tag engine (e.g. "TOP"). Indicates where on the product card the badge should be rendered. null if the tag engine does not specify a position.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
filters
array of object (SearchFilterItem)
Active faceted filters available for this result set. Each filter has a `key` object (display, name, kind, logo) and a `values` array. When `more_filter_categories` is requested, matching category-specific filters carry `is_more_filter: true` and `category_slug` so the UI can render them in a separate "More Filters" section.
Array of SearchFilterItem
key
object (SearchFilterKey)
SearchFilterKey
display
string
Human-readable display name for the filter.
name
string
Machine-readable filter identifier.
kind
string
Filter interaction type.
Enum
logo
string
Nullable
Optional logo URL for the filter.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
values
array of object
Available filter values for this key.
is_more_filter
boolean
Present and true when this filter originates from a category-specific "More Filters" config (requested via more_filter_categories query param).
category_slug
string
The category slug this filter belongs to. Only present when is_more_filter is true.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
page
object
Pagination metadata for the current result page.
sort_on
array of object
Available sort options for the result set.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
Examples
Parameters
Parameters are not required.
Was this section helpful?
GET
Response
Lists all products.
getProducts
FDK Method Name: getCollectionProducts
Returns a paginated product listing filtered to the given collection slug. Supports both handpick and rules-based collections — the Vertex filter expression is resolved by the collection service; this endpoint has no branching logic.
Parameters
slug
string
Required
Collection slug identifier (e.g. summer-sale, new-arrivals).
f
string
Filter string — same format as /products (key:val:::key:val).
sort_on
string
Sort key — same values as /products.
Enum
page_id
string
Cursor token for the next page.
page_size
integer
Number of results per page.
Default Value : 12
page_no
integer
Page number (1-indexed).
Default Value : 1
page_type
string
Pagination mode — cursor or number.
Default Value : cursor
Enum
store_ids
string
Comma-separated store / channel IDs (e.g. "AJIO,AJIO_INTL")
more_filter_categories
string
Comma-separated category slugs for "More Filters" — same behavior as the /products endpoint.
Response
200
404
Success. Returns a paginated product listing for the collection.
SearchProductListing
items
array of object (SearchProductItem)
Paginated list of organic and sponsored product items.
Array of SearchProductItem
uid
integer
Unique product identifier.
name
string
Product display name.
slug
string
URL-safe product identifier.
item_type
string
Always "standard" for PRIMARY-type catalog.
sellable
boolean
Whether the product is currently purchasable.
discount
string
Formatted discount string (e.g. "20% OFF"). Empty string when no discount.
brand
object
Brand name, uid, logo, and navigation action.
price
object
Price object with effective, marked, and selling legs. Each leg has min/max/currency_code/currency_symbol.
medias
array of object
Product images (type=image, url).
action
object
Navigation action for deep-linking to the product detail page.
_custom_json
object
Arbitrary key-value metadata from the catalog.
tags
array of string
Product tags from the catalog (e.g. "Single", "Mass"). Empty array when no tags are present.
sponsored
boolean
Present and true only for Osmos PLA sponsored products injected into the listing. Absent on organic products.
ad_meta
object (AdMeta)
AdMeta
uclid
string
Unique click link ID for Osmos impression/click tracking.
mcid
string
Merchant click ID.
sclid
string
Search click link ID.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
primary_urgency_tag
object (UrgencyTag)
Nullable
Highest-priority urgency tag for this product, resolved by the tag engine at search time. Present only when TAG_ENGINE_ENABLED=true and the tag engine returns a tag for this product. null when no urgency tag applies.
UrgencyTag
tag_name
string
Internal tag identifier used for filtering and analytics.
short_text
string
Display label shown on the product card badge.
icon_url
string
CDN URL of the badge icon to render on the product card.
position
string
Nullable
Tag placement position returned by the tag engine (e.g. "TOP"). Indicates where on the product card the badge should be rendered. null if the tag engine does not specify a position.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
filters
array of object (SearchFilterItem)
Active faceted filters available for this result set. Each filter has a `key` object (display, name, kind, logo) and a `values` array. When `more_filter_categories` is requested, matching category-specific filters carry `is_more_filter: true` and `category_slug` so the UI can render them in a separate "More Filters" section.
Array of SearchFilterItem
key
object (SearchFilterKey)
SearchFilterKey
display
string
Human-readable display name for the filter.
name
string
Machine-readable filter identifier.
kind
string
Filter interaction type.
Enum
logo
string
Nullable
Optional logo URL for the filter.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
values
array of object
Available filter values for this key.
is_more_filter
boolean
Present and true when this filter originates from a category-specific "More Filters" config (requested via more_filter_categories query param).
category_slug
string
The category slug this filter belongs to. Only present when is_more_filter is true.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
page
object
Pagination metadata for the current result page.
sort_on
array of object
Available sort options for the result set.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
Examples
Parameters
Parameters are not required.
Was this section helpful?
GET
Response
Browse products belonging to a collection.
getCollectionProducts
FDK Method Name: getFilterConfig
Returns the base filter configuration (from catalog Redis) merged with Phoenix overrides, plus category-specific filter mappings for the "More Filters" UX. Lightweight endpoint — Redis/Mongo only, no Vertex call.
Parameters
No Parameters
Response
200
400
Success. Returns primary and category filter configurations.
FilterConfigResult
data
object (FilterConfigData)
FilterConfigData
primary_filters
array of object (FilterConfigPrimaryFilter)
Base filters sorted by priority.
Array of FilterConfigPrimaryFilter
key
string
Filter attribute key.
display_name
string
Human-readable display name.
kind
string
Filter interaction type.
logo
string
Nullable
Optional logo URL.
priority
integer
Sort priority for display ordering.
_source
string
Origin of this filter config — "catalog" or "phoenix".
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
category_filters
array of object (FilterConfigCategoryFilter)
Category-specific filter groups for "More Filters" UX.
Array of FilterConfigCategoryFilter
slug
string
Category slug identifier.
name
string
Category display name.
group
string
Nullable
Optional grouping label for the category filter set.
filters
array of object (FilterConfigCategoryFilterEntry)
Filters within this category group.
Array of FilterConfigCategoryFilterEntry
attribute_key
string
Attribute key for this filter.
display_name
string
Human-readable display name.
output_key
string
Key used in the filter output/query.
kind
string
Filter interaction type.
priority
integer
Sort priority for display ordering.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
error
object
Nullable
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
Examples
Parameters
Parameters are not required.
Was this section helpful?
GET
Response
Get filter configuration.
getFilterConfig
FDK Method Name: getImageSearchProducts
Search for visually similar products by uploading an image (image_name) or refining a prior search using a ViSenze image ID (im_id + box). Returns the same product listing shape as /products plus a visual block containing the ViSenze session ID and detected product types.
Parameters
image_name
string
GCS object name or public image URL for a new visual search.
im_id
string
ViSenze im_id from a prior image search response (refinement flow).
box
string
Bounding box "x1,y1,x2,y2" — required when im_id is provided.
store
string
ViSenze store key for per-store credential resolution.
f
string
Filter string — same format as /products (key:val:::key:val).
sort_on
string
Sort key — same values as /products.
Enum
page
integer
0-indexed page number.
Default Value : 0
page_size
integer
Results per page (max 100).
Default Value : 20
product_type
string
Detected product type tag (e.g. outerwear, shoe). Actual filtering uses im_id + box.
store_ids
string
Comma-separated store / channel IDs (e.g. "AJIO,AJIO_INTL")
Response
200
Success. Returns a paginated product listing with visual session metadata.
ImageSearchProductListing
items
array of object
Paginated list of visually similar product items.
filters
array of object
Active faceted filters available for this result set.
page
object
Pagination metadata for the current result page.
sort_on
array of object
Available sort options for the result set.
visual
object (VisualSearchBlock)
VisualSearchBlock
id
string
ViSenze session image ID for refinement flows.
product_types
array of object
List of detected product types with confidence scores and bounding boxes.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
Examples
Parameters
Parameters are not required.
Was this section helpful?
GET
Response
Visual image-based product search.
getImageSearchProducts
FDK Method Name: getAutoComplete
Get products, brands, or categories based on a search query, which can be a partial or full name match.
Parameters
q
string
Required
The search query for entering partial or full name of a product, brand or category. For example, if the given search query `q` is _ski_, the relevant search suggestions could be _skirt_, _ski shoes_, _skin cream_ etc.
store_ids
string
Comma-separated store / channel IDs (e.g. "AJIO,AJIO_INTL")
Response
200
Success. Returns a list of autocomplete suggestions for the search query `q`.
SearchAutoComplete
items
array of object
List of autocomplete suggestion items.
additionalProperties
Allows you to attach properties in addition to the ones mentioned above. Any additional properties are allowed.
Examples
Parameters
Parameters are not required.
Was this section helpful?
GET
Response