The facetted recommendations api allows retrieval of the most recommended garments for a user. The result set can be filtered by specifying one or more filters. Optionally retrieval of information about the number of hits for other values of the filter are returned
The currently recognized aggregations are
- garment_category
- brand
- occasion
- must_have
- retailer_labels (previously known as retailer_categories): significance dependent on the retailer and your product data
- store: if Mapp Fashion has been provided with per-store availability data, this filters or aggregates on availability by store
- feature_ids (Mapp Fashion feature ids)
- not_features_ids (Mapp Fashion feature ids). This returns results without any of the listed feature ids
- price
- reduced_by (range filter that accepts values from 0 to 100)
- season: filters or aggregates on the season a garment belongs to. Allowed season codes are of the form
ss_YYYY(spring/summer) oraw_YYYY(autumn/winter), e.g.ss_2024,aw_2024
The retailer_labels aggregation allows you to query against fields in your product data consumed by Mapp Fashion (these should be agreed with Mapp Fashion)
For example to request a garment category of 1 (dresses) submit
{
"facets": [
{
"name": "garment_category",
"value": [1]
}
]
}
Multiple values can be passed for a single filter, these will be or-ed.
For example, to select garments that have all of
- feature id 1 or 2,
- feature id 3 or 4
submit
{
"facets": [
{
"name": "feature_ids",
"filters": [
{"value": [1,2]},
{"value": [3,4]}
]
}
]
}
Multiple filters can be passed, these will be and-ed (Specifying multiple filters with the same name is not supported) For example, to return items matching a specific retailer label and available from a specific store, submit
{
"facets": [
{
"name": "retailer_labels",
"value": [1,2]
},
{
"name": "store",
"value": ["storeID1","storeID2"]
}
]
}
If the size for a facet is set to non 0, count information will be returned about other filter values. Conceptually, the count returned in an agggregation bucket is the number of results you would get if the query was filtered by that aggregation value.
Numerical facets use a slightly different syntax, for example
{
"facets": [
{
"name": "price",
"filters": [
{
"from": 50,
"to": 100
}
],
"ranges": [
{"to": 50},
{"from": 50, "to": 100},
{"from": 100}
]
}
]
}
returns items whose price between 50 (inclusive) and 100 and the number of results within each of the indicated price ranges.
{
"facets": [
{
"name": "reduced_by",
"filters": [
{
"from": 30
}
]
}
]
}
Returns items reduced by at least 30%
{
"facets": [
{
"name": "season",
"filters": [
{"value": ["ss_2026"]}
]
}
]
}
Returns items belonging to the Spring/Summer 2026 season
Depending on the garment_format requested, extra fields may be present on the garment, however garment_id and raw_garment_id
will always be present
The JWT for the user. Optional: requests without a user token return non-personalized results. The header name is unchanged for backwards compatibility.
The desired response format.
The response includes a description of the outfits / similar items but no data on the items themselves: since these may be repeated within the response, garment data is provided separately in the response.
The detailed format includes the most amount of item metadata (name, description, price etc).
The document format only includes item identifiers, and if requested Mapp Fashion generated information about the item, such as predicted size.
The retailer_ids format only returns the item identifiers.
Deprecated. This parameter still returns data, but the logic behind it is no longer maintained and it has no v2 equivalent. Do not rely on it for new integrations.
A list of garment attributes to fetch. Only supported for garment_format=document or detailed. Retailer specific custom fields are named x-<field> and may be requested in addition to the values listed here - contact Mapp Fashion for details
If true, pretty print JSON output. This increases response size and should usually be off in production environments
Controls whether Mapp Fashion garment ids (raw_garment_id) are included in response
The page from which to start results
The number of result to return per page
A device type identifier. This allows segmenting a/b test statistics in the same way as you do.
A locale parameter describing what stock information to use and what language to return text in (if applicable). This parameter will only function if the corresponding information is in your product data & processed accordingly. If stock local and UI language are not the same, specify the language parameter in addition to this one.
Allows you to specify a locale used for product attributes such as product name that should be localized using a different locale to price & stock information. This parameter will only function if the corresponding information is in your product data & processed accordingly.
Restricts the results to garments for the given season, written as ss_ or aw_ followed by the year, for example aw_2025.
return facetted recommendations for a user
When requesting the 2nd or later pages of recommendations, provide the root_event_id from the previous page
The name of the facet. retailer_categories is deprecated, use retailer_labels instead.
The values to filter by (deprecated in favor of the filters parameter)
The number of facet entries to retrieve. The feature_ids and not_feature_ids facets do not support non zero sizes
An array of filters, that will be added together. Each filter has a value property which is the array of values to match against
the array of permitted values
for numerical facets, the minimum value
for numerical facets, the maximum value
the type of identifiers in the value of a filter with name name, default is 'product-code' when unspecified
For numerical facets, a list of ranges for which to retrieve counts
the type of identifiers in the value of a filter with name name, default is 'product-code' when unspecified
Information about the recommended garments
Retrieve items that the user has previously liked filtered by garment category.
For example to request a garment category of 1 (dresses) submit
{
"facets": [
{
"name": "garment_category",
"value": [1]
}
]
}
An event id. This should be used when posting events relating to this dataset.
The currency the prices in this response are expressed in, resolved from the requested locale (the default currency if no locale is given). Null if your product data contains no currency
If true, the eventid should be posted to /events//reparent
An opaque identifier identifying this section of the response. This should be used when posting events relating to an item in this outfit.
The recommended items
Fetches information about a garment. The garment format is implicitly set to detailed.
The garment_id. The type of identifier used depends on the requests' garment_format
The internal Mapp Fashion id for the garment. This may be omitted depending on garment_format
The product level identifier the item belongs to (Product ID in the Product Catalog), grouping all its colors and sizes. Omitted if your product data contains no Product ID
An alternative identifier to identify the product, hidden when not provided in your product data
Whether garment has extended verdicts. Only presents for verdicts/dislikes, also not present if format=retailer_ids
Whether outfits can be generated. not present if format=retailer_ids
Information about the recommended size
Information about size immediately bigger than the recommended one (if available)
Information about size immediately smaller than the recommended one (if available)
If whys have been requested & if the profile has shape data, a list of human readable reasons for recommendation
If verdicts have been requested, the approval status of the garment (true=like, false=dislike, nil=no verdict given)
If owned has been requested, whether the use has previously purchased the product
A numerical score for the garment (out of 10)
A human readable interpretation of the score
If features have been requested, a list of whitelisted feature objects
The id for the feature
The human readable name for the feature
The feature category of the feature
The category id for the product.
The garment department (female male girls boys).
If eans have been requested, the array of eans present in your product data.
The category name for the product.
Array of the product occasions. Only present if format=detailed, and only populated when occasions is requested via fields; otherwise the key may be returned as null. The possible values are casual, evening, occasion, holiday, work and creative_work
The retailer name for the product. Only present if format=detailed
The array of image_urls present in your product data. Only present if format=detailed
The brand name for the product. Only present if format=detailed
The product name. Only present if format=detailed
The current price, as it appears in your product data. Only present if format=detailed
The previous price, as it appears in your product data. Only present if format=detailed
The URL for the PDP for the garment. Only present if format=detailed
The status of the garment. Only present if format=detailed
Product attributes, as agreed with Mapp Fashion
The name of the attribute
The value of the attribute (if string valued)
The value of the attribute (if array valued)
The requested facet information
The name of the facet
The returned buckets for the facet
For non numeric facets, the id of the bucket, usable as search values in subsequent requests
For non numeric facets, a human readable description of the bucket
The approximate number of items matching the value
For numeric facets, the lower endpoint of the bucket
For numeric facets, the upper endpoint of the bucket
The total number of pages that can be requested
The total number of results that can be requested
The current page
The variant SKUs of the recommended items that are still in stock, one entry per item. An empty array when none are known.
Only reliable if the variant IDs are maintained in the Product Catalog and the products have their real product images from the first import on. Products imported with placeholder images or dummy URLs can receive SKUs of other products.
The in-stock variant SKUs of one recommended item.
The item the SKUs belong to, as returned in garment_id
The variant SKUs of the item that are still in stock
Warnings about ignored or adjusted request parameters
One or more parameter values are invalid
Generic error object
A human readable error message
Invalid JWT: a user token was supplied but could not be verified. Requests without a user token are not affected - they return non-personalized results
Generic error object
A human readable error message
error message
Generic error object
A human readable error message
An internal error occurred. Retry the request. If the issue persists, contact Technical Support
Generic error object
A human readable error message