--- title: Get Recommended Variants slug: api-documentation/get-recommended-variants docTags: createdAt: 2026-08-27T16:53:40.115Z --- { "id": "Y61EJ4bpA2pA-kk5axm4r", "type": "api-oas-v2", "data": { "method": "GET", "url": "https://api.upstartcommerce.com/v1/catalog/live/recommendation/variant/{skuId}", "servers": [ { "url": "https://api.upstartcommerce.com/v1/catalog/live/recommendation/variant/{skuId}" } ], "name": "Get Recommended Variants", "description": "

DESCRIPTION:

\n

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

\n

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

\n

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

\n

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

\n

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

\n

KEY FEATURES:

\n", "contentType": "application/json", "request": { "pathParameters": [ { "kind": "required", "name": "skuId", "type": "string", "description": "

Unique identifier for the SKU (variant) item.

" } ], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "application/json" ], "default": "application/json" }, { "kind": "required", "name": "x-upstart-tenant", "type": "string", "description": "Tenant identifier associated with the site this call is for." }, { "kind": "required", "name": "x-upstart-site", "type": "string", "description": "Unique identifier for the site." } ], "queryParameters": [ { "kind": "optional", "name": "recommendationType", "type": "string", "description": "

Represents the type to get recommendation against. Optional; similar is applied when the parameter is omitted or blank.

", "enum": [ "frequently_bought", "visually_similar", "similar" ] }, { "kind": "optional", "name": "top_k", "type": "string", "description": "

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

" }, { "kind": "optional", "name": "customer_id", "type": "string", "description": "

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

" } ], "bodyDataParameters": [], "formDataParameters": [], "oAuthParameters": [ { "id": "AnonymousAuth", "name": "AnonymousAuth", "kind": "optional", "type": "http", "description": "This is the most basic authentication. The minimum requirement for access is a token representing the user as an anonymous client.", "scheme": "bearer" }, { "id": "LoggedIn", "name": "LoggedIn", "kind": "optional", "type": "http", "description": "The presence of this token indicates that the user is a known consumer that has previously logged into the platform.", "scheme": "bearer" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "

Success - recommendations holds the recommended variants and may be empty.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "

SKU-level (\"variant\") recommendations for the requested SKU, ordered by descending model score.

", "customType": "VariantRecommendationsResponse", "schema": [ { "name": "skuId", "kind": "required", "type": "string", "description": "

The SKU that was requested, echoed back.

", "modelRef": "#/components/schemas/SkuItemId", "customType": "SkuItemId", "schema": [] }, { "name": "customerId", "kind": "optional", "type": "string", "description": "

The customer whose already-purchased SKUs were excluded from the results. Omitted when no customer was supplied, or when the recommendation model applied no personalization.

" }, { "name": "recommendations", "kind": "required", "type": "array", "description": "

Recommended SKUs, at most top_k entries. Empty when the model has none for this SKU.

", "modelRef": "#/components/schemas/CatalogItemVariantRecommendation", "customType": "CatalogItemVariantRecommendation[]", "schema": [ { "name": "skuId", "kind": "required", "type": "string", "description": "", "modelRef": "#/components/schemas/SkuItemId", "customType": "SkuItemId", "schema": [] }, { "name": "score", "kind": "required", "type": "number", "description": "

Merged weighted-cosine similarity score produced by the recommendation model.

", "format": "double" }, { "name": "catalogItemId", "kind": "required", "type": "string", "description": "Identifier of the parent catalog item that owns this SKU.", "modelRef": "#/components/schemas/CatalogItemId", "customType": "CatalogItemId", "schema": [] }, { "name": "sku", "kind": "required", "type": "object", "discriminator": { "propertyName": "type", "mapping": { "product": "#/components/schemas/ProductItemSummary", "protectionPlan": "#/components/schemas/ProtectionPlanItemSummary", "service": "#/components/schemas/ServiceItemSummary", "warranty": "#/components/schemas/WarrantyItemSummary" } }, "description": "", "modelRef": "#/components/schemas/SkuItemSummary", "customType": "SkuItemSummary", "schema": [], "complexType": "oneOf", "complexItems": [ { "name": "ProductItemSummary", "description": "", "modelRef": "#/components/schemas/ProductItemSummary", "schema": [ { "name": "brandName", "kind": "optional", "type": "string", "description": "" }, { "name": "dimensions", "kind": "optional", "type": "object", "deprecated": true, "description": "Warning: Deprecated\n

Dimensions of the product item (deprecated, use skuDimensions instead)

", "modelRef": "#/components/schemas/Dimensions", "customType": "Dimensions", "schema": [ { "name": "width", "kind": "required", "type": "number", "description": "", "example": 18.5, "format": "double" }, { "name": "length", "kind": "required", "type": "number", "description": "", "example": 18.5, "format": "double" }, { "name": "height", "kind": "required", "type": "number", "description": "", "example": 18.5, "format": "double" }, { "name": "unit", "kind": "required", "type": "string", "description": "", "enum": [ "cm", "m", "in", "mm" ] } ] }, { "name": "disabled", "kind": "optional", "type": "boolean", "description": "", "default": false }, { "name": "dynamicProperties", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [] }, { "name": "ignoreInventory", "kind": "optional", "type": "boolean", "description": "" }, { "name": "manufactureName", "kind": "optional", "type": "string", "description": "" }, { "name": "media", "kind": "optional", "type": "map", "description": "", "example": "", "customType": "map", "schema": [] }, { "name": "name", "kind": "optional", "type": "string", "description": "Name for the product item." }, { "name": "numPieces", "kind": "optional", "type": "integer", "description": "", "format": "int32", "minimum": 0, "exclusiveMinimum": true }, { "name": "pricing", "kind": "optional", "type": "object", "description": "", "modelRef": "#/components/schemas/Pricing", "customType": "Pricing", "schema": [ { "name": "currency", "kind": "required", "type": "string", "description": "", "example": "USD", "pattern": "^[A-Z]{3}$" }, { "name": "price", "kind": "required", "type": "number", "description": "" } ] }, { "name": "purchasable", "kind": "required", "type": "boolean", "description": "", "default": true }, { "name": "shippingMethodIds", "kind": "optional", "type": "array", "description": "", "modelRef": "#/components/schemas/ShippingMethodId", "customType": "ShippingMethodId[]", "schema": [] }, { "name": "shippingPackages", "kind": "required", "type": "array", "description": "", "modelRef": "#/components/schemas/ShippingPackage", "customType": "ShippingPackage[]", "schema": [ { "name": "dimensions", "kind": "required", "type": "object", "description": "This is a common definition of a dimension.", "modelRef": "#/components/schemas/Dimensions", "customType": "Dimensions", "schema": [ { "name": "width", "kind": "required", "type": "number", "description": "", "example": 18.5, "format": "double" }, { "name": "length", "kind": "required", "type": "number", "description": "", "example": 18.5, "format": "double" }, { "name": "height", "kind": "required", "type": "number", "description": "", "example": 18.5, "format": "double" }, { "name": "unit", "kind": "required", "type": "string", "description": "", "enum": [ "cm", "m", "in", "mm" ] } ] }, { "name": "weight", "kind": "required", "type": "object", "description": "Defines a common structure for representing weights.", "modelRef": "#/components/schemas/Weight", "customType": "Weight", "schema": [ { "name": "value", "kind": "required", "type": "number", "description": "", "format": "double", "minimum": 0 }, { "name": "unit", "kind": "required", "type": "string", "description": "Unit of measurement.", "enum": [ "g", "kg", "lb" ] } ] } ] }, { "name": "skuId", "kind": "required", "type": "string", "description": "", "modelRef": "#/components/schemas/SkuItemId", "customType": "SkuItemId", "schema": [] }, { "name": "tags", "kind": "optional", "type": "array", "description": "", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "weight", "kind": "optional", "type": "object", "description": "Defines a common structure for representing weights.", "modelRef": "#/components/schemas/Weight", "customType": "Weight", "schema": [ { "name": "value", "kind": "required", "type": "number", "description": "", "format": "double", "minimum": 0 }, { "name": "unit", "kind": "required", "type": "string", "description": "Unit of measurement.", "enum": [ "g", "kg", "lb" ] } ] }, { "name": "upc", "kind": "optional", "type": "string", "description": "" }, { "name": "feeMultiplier", "kind": "optional", "type": "integer", "description": "", "format": "int32" }, { "name": "skuDimensions", "kind": "optional", "type": "array", "description": "This is a common definition of a sku's dimension.", "modelRef": "#/components/schemas/DimensionsInfo", "customType": "DimensionsInfo[]", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "" }, { "name": "description", "kind": "optional", "type": "string", "description": "" }, { "name": "width", "kind": "required", "type": "number", "description": "", "example": 18.5, "format": "double" }, { "name": "length", "kind": "required", "type": "number", "description": "", "example": 18.5, "format": "double" }, { "name": "height", "kind": "required", "type": "number", "description": "", "example": 18.5, "format": "double" }, { "name": "unit", "kind": "required", "type": "string", "description": "", "enum": [ "cm", "m", "in", "mm" ] } ] } ] }, { "name": "ProtectionPlanItemSummary", "description": "", "modelRef": "#/components/schemas/ProtectionPlanItemSummary", "schema": [ { "name": "description", "kind": "required", "type": "string", "description": "" }, { "name": "disabled", "kind": "required", "type": "boolean", "description": "" }, { "name": "name", "kind": "required", "type": "string", "description": "" }, { "name": "purchasable", "kind": "required", "type": "boolean", "description": "" }, { "name": "skuId", "kind": "required", "type": "string", "description": "" }, { "name": "dynamicProperties", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [] }, { "name": "pricing", "kind": "optional", "type": "object", "description": "", "modelRef": "#/components/schemas/Pricing", "customType": "Pricing", "schema": [ { "name": "currency", "kind": "required", "type": "string", "description": "", "example": "USD", "pattern": "^[A-Z]{3}$" }, { "name": "price", "kind": "required", "type": "number", "description": "" } ] }, { "name": "type", "kind": "required", "type": "string", "description": "", "default": "protectionPlan", "enum": [ "bundle", "product", "protectionPlan", "service", "warranty", "fee" ] }, { "name": "termsAndConditions", "kind": "required", "type": "object", "discriminator": { "propertyName": "type", "mapping": { "UrlTermsAndConditions": "#/components/schemas/UrlTermsAndConditions", "DrupalTermsAndConditions": "#/components/schemas/DrupalTermsAndConditions", "CloudinaryAsset": "#/components/schemas/CloudinaryAssetUpdate" } }, "description": "", "modelRef": "#/components/schemas/TermsAndConditions", "customType": "TermsAndConditions", "schema": [], "complexType": "oneOf", "complexItems": [ { "name": "UrlTermsAndConditions", "description": "", "modelRef": "#/components/schemas/UrlTermsAndConditions", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "DrupalTermsAndConditions", "description": "", "modelRef": "#/components/schemas/DrupalTermsAndConditions", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "CloudinaryAssetUpdate", "description": "", "modelRef": "#/components/schemas/CloudinaryAssetUpdate", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] } ] } ] }, { "name": "ServiceItemSummary", "description": "", "modelRef": "#/components/schemas/ServiceItemSummary", "schema": [ { "name": "description", "kind": "required", "type": "string", "description": "" }, { "name": "disabled", "kind": "optional", "type": "boolean", "description": "", "default": false }, { "name": "dynamicProperties", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [] }, { "name": "name", "kind": "required", "type": "string", "description": "" }, { "name": "pricing", "kind": "optional", "type": "object", "description": "", "modelRef": "#/components/schemas/Pricing", "customType": "Pricing", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "purchasable", "kind": "required", "type": "boolean", "description": "", "default": true }, { "name": "skuId", "kind": "required", "type": "string", "description": "", "modelRef": "#/components/schemas/SkuItemId", "customType": "SkuItemId", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "termsAndConditions", "kind": "optional", "type": "object", "discriminator": { "propertyName": "type", "mapping": { "DrupalTermsAndConditions": "#/components/schemas/DrupalTermsAndConditionsUpdate", "CloudinaryAsset": "#/components/schemas/CloudinaryAssetUpdate" } }, "description": "", "modelRef": "#/components/schemas/GeneralTermsAndConditions", "customType": "GeneralTermsAndConditions", "schema": [], "complexType": "oneOf", "complexItems": [ { "name": "DrupalTermsAndConditionsUpdate", "description": "", "modelRef": "#/components/schemas/DrupalTermsAndConditionsUpdate", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] }, { "name": "CloudinaryAssetUpdate", "description": "", "modelRef": "#/components/schemas/CloudinaryAssetUpdate", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] } ] }, { "name": "type", "kind": "required", "type": "string", "description": "", "default": "service", "enum": [ "product", "protectionPlan", "service", "warranty" ] } ] }, { "name": "WarrantyItemSummary", "description": "", "modelRef": "#/components/schemas/WarrantyItemSummary", "schema": [ { "name": "", "description": "", "customType": "Max depth limit reached" } ] } ] } ] } ], "modelRef": "#/components/schemas/VariantRecommendationsResponse", "isExpanded": true } ] }, { "statusCode": "400", "description": "The request contained information that the server was unable to process. Appropriate errors are provided in the response body.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ValidationErrorResponse", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "" }, { "name": "code", "kind": "required", "type": "string", "description": "" }, { "name": "detail", "kind": "optional", "type": "string", "description": "" } ], "modelRef": "#/components/schemas/ValidationErrorResponse", "isExpanded": true } ] }, { "statusCode": "401", "description": "The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ErrorResponse", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "" }, { "name": "code", "kind": "required", "type": "string", "description": "" }, { "name": "detail", "kind": "required", "type": "string", "description": "" }, { "name": "reason", "kind": "optional", "type": "string", "description": "" } ], "modelRef": "#/components/schemas/ErrorResponse", "isExpanded": true } ] }, { "statusCode": "404", "description": "The requested resource was not found in the NoChannel system.", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ErrorResponse", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "" }, { "name": "code", "kind": "required", "type": "string", "description": "" }, { "name": "detail", "kind": "required", "type": "string", "description": "" }, { "name": "reason", "kind": "optional", "type": "string", "description": "" } ], "modelRef": "#/components/schemas/ErrorResponse", "isExpanded": true } ] }, { "statusCode": "502", "description": "

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

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ErrorResponse", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "" }, { "name": "code", "kind": "required", "type": "string", "description": "" }, { "name": "detail", "kind": "required", "type": "string", "description": "" }, { "name": "reason", "kind": "optional", "type": "string", "description": "" } ], "modelRef": "#/components/schemas/ErrorResponse", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "JPPV7fPc5dXSwmLvty8Mg", "language": "curl", "label": "cURL", "code": "curl --request GET \\\n --url https://api.upstartcommerce.com/v1/catalog/live/recommendation/variant/{skuId} \\\n --header 'accept: application/json' \\\n --header 'x-upstart-tenant: string' \\\n --header 'x-upstart-site: string'" }, { "id": "s6w7Orl-BNTru0ALdKBMN", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\nmyHeaders.append(\"x-upstart-tenant\", \"string\");\nmyHeaders.append(\"x-upstart-site\", \"string\");\n\nvar requestOptions = {\n method: 'GET',\n headers: myHeaders,\n redirect: 'follow'\n};\n\nfetch(\"https://api.upstartcommerce.com/v1/catalog/live/recommendation/variant/{skuId}\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "ZnMyjv2BUuYF8vLLp02LC", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.upstartcommerce.com/v1/catalog/live/recommendation/variant/{skuId}\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Get.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest[\"x-upstart-tenant\"] = \"string\"\nrequest[\"x-upstart-site\"] = \"string\"\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "H-38_joSafyN33DvkL8Df", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.upstartcommerce.com/v1/catalog/live/recommendation/variant/{skuId}\"\n\npayload = {}\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json',\n 'x-upstart-tenant': 'string',\n 'x-upstart-site': 'string'\n}\n\nresponse = requests.request(\"GET\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "JPPV7fPc5dXSwmLvty8Mg" }, "results": { "languages": [ { "id": "WnbgfQgd_j8FiWQlbyfTD", "language": "200", "code": "// Success - recommendations holds the recommended variants and may be empty.\n{\n \"skuId\": \"\",\n \"customerId\": \"\",\n \"recommendations\": [\n {\n \"skuId\": \"\",\n \"score\": \"\",\n \"catalogItemId\": \"\",\n \"sku\": {}\n }\n ]\n}" }, { "id": "FuLBEq5imw97E7y_pT3HE", "language": "400", "code": "// The request contained information that the server was unable to process. Appropriate errors are provided in the response body.\n{\n \"name\": \"\",\n \"code\": \"\",\n \"detail\": \"\"\n}" }, { "id": "HXjS03w6grNZzOZBJeDnC", "language": "401", "code": "// The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.\n{\n \"name\": \"\",\n \"code\": \"\",\n \"detail\": \"\",\n \"reason\": \"\"\n}" }, { "id": "ehdHSMKTeZCOnznmNJynO", "language": "404", "code": "// The requested resource was not found in the NoChannel system.\n{\n \"name\": \"\",\n \"code\": \"\",\n \"detail\": \"\",\n \"reason\": \"\"\n}" }, { "id": "kGO_2TBSqrLxQMydjiqkg", "language": "502", "code": "// An upstream service this endpoint depends on was unavailable, timed out, or returned an unusable response.\n{\n \"name\": \"\",\n \"code\": \"\",\n \"detail\": \"\",\n \"reason\": \"\"\n}" } ], "selectedLanguageId": "WnbgfQgd_j8FiWQlbyfTD" } }, "children": [ { "text": "" } ] }