Get Recommended Variants

1 min

GET

https://api.upstartcommerce.com/v1/catalog/live/recommendation/variant/{skuId}

DESCRIPTION:

The Get Recommended Variants API returns SKU-level ("variant") recommendations for a single SKU. Where the Get Recommended Items API answers "which other products go with this one", this API answers "which other variants are like this one" - the recommended SKU, its model score, and its own SKU data are returned for every recommendation.

Only the recommended SKU is returned, not its parent catalog item and not the parent's other SKUs. Each entry carries catalogItemId so the parent can be fetched when product-level data is needed.

Recommendations are ranked by descending model score and preserve that order in the response. Two recommended SKUs belonging to the same product produce two independent entries.

Results are restricted to the brand of the input SKU's parent product whenever that brand is listed in the site's catalog / brands configuration; when the brand is absent from the product or from that configuration, all recommendations are returned. Site authorization and the live activation window are applied in every case.

An empty recommendations array - not a 404 - is returned when the model has no recommendations for the SKU, or when every recommendation is filtered out. A 404 means the requested skuId itself does not resolve to a live catalog item.

KEY FEATURES:

Variant-level rather than product-level suggestions
Model score returned alongside every recommendation
Brand-specific results driven by portal configuration
Optional personalization that excludes a customer's already-purchased SKUs

skuIdstringUnique identifier for the SKU (variant) item.

recommendationTypestringRepresents the type to get recommendation against. Optional; <code>similar</code> is applied when the parameter is omitted or blank.

top_kstringMaximum number of recommended variants to return (positive integer). Defaults to 20.

customer_idstringOptional customer identifier. When supplied, SKUs the customer has already purchased are excluded from the results. Omitted from the downstream call when absent.

acceptstringGenerated from available response content types

x-upstart-tenantstringTenant identifier associated with the site this call is for.

x-upstart-sitestringUnique identifier for the site.

200Success - <code>recommendations</code> holds the recommended variants and may be empty.

400The request contained information that the server was unable to process. Appropriate errors are provided in the response body.

401The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.

404The requested resource was not found in the NoChannel system.

502An upstream service this endpoint depends on was unavailable, timed out, or returned an unusable response.

curl --request GET \
     --url https://api.upstartcommerce.com/v1/catalog/live/recommendation/variant/{skuId} \
     --header 'accept: application/json' \
     --header 'x-upstart-tenant: string' \
     --header 'x-upstart-site: string'