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

Path Parameters

skuIdstringrequired
Description
Unique identifier for the SKU (variant) item.

Query Parameters

recommendationTypestring
Description
Represents the type to get recommendation against. Optional; similar is applied when the parameter is omitted or blank.
Allowed
frequently_boughtvisually_similarsimilar
top_kstring
Description
Maximum number of recommended variants to return (positive integer). Defaults to 20.
customer_idstring
Description
Optional customer identifier. When supplied, SKUs the customer has already purchased are excluded from the results. Omitted from the downstream call when absent.

Header Parameters

x-upstart-tenantstringrequired
Description
Tenant identifier associated with the site this call is for.
x-upstart-sitestringrequired
Description
Unique identifier for the site.

Responses

200

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

VariantRecommendationsResponse
Description
SKU-level ("variant") recommendations for the requested SKU, ordered by descending model score.
- skuIdSkuItemIdrequired
  Description
  The SKU that was requested, echoed back.
- customerIdstring
  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.
- recommendationsCatalogItemVariantRecommendation[]required
  Description
  Recommended SKUs, at most top_k entries. Empty when the model has none for this SKU.
  - skuIdSkuItemIdrequired
  - scorenumber<double>required
    Description
    Merged weighted-cosine similarity score produced by the recommendation model.
    Format
    double
  - catalogItemIdCatalogItemIdrequired
    Description
    Identifier of the parent catalog item that owns this SKU.
  - skuSkuItemSummaryrequired
    - ProductItemSummary
      - brandNamestring
      - dimensionsDimensions
        Description
        Warning: Deprecated
        Dimensions of the product item (deprecated, use skuDimensions instead)
        widthnumber<double>required
        Example
        18.5
        Format
        double
        lengthnumber<double>required
        Example
        18.5
        Format
        double
        heightnumber<double>required
        Example
        18.5
        Format
        double
        unitstring<cm | m | in | mm>required
        Allowed
        cmminmm
      - disabledboolean
        Default
        false
      - dynamicPropertiesobject
      - ignoreInventoryboolean
      - manufactureNamestring
      - mediamap<string, MediaValue>
      - namestring
        Description
        Name for the product item.
      - numPiecesinteger<int32>
        Format
        int32
        Minimum (exclusive)
        0
      - pricingPricing
        currencystringrequired
        Example
        USD
        Pattern
        ^[A-Z]{3}$
        pricenumberrequired
      - purchasablebooleanrequired
        Default
        true
      - shippingMethodIdsShippingMethodId[]
      - shippingPackagesShippingPackage[]required
        dimensionsDimensionsrequired
        Description
        This is a common definition of a dimension.
        widthnumber<double>required
        Example
        18.5
        Format
        double
        lengthnumber<double>required
        Example
        18.5
        Format
        double
        heightnumber<double>required
        Example
        18.5
        Format
        double
        unitstring<cm | m | in | mm>required
        Allowed
        cmminmm
        weightWeightrequired
        Description
        Defines a common structure for representing weights.
        valuenumber<double>required
        Format
        double
        Minimum
        0
        unitstring<g | kg | lb>required
        Description
        Unit of measurement.
        Allowed
        gkglb
      - skuIdSkuItemIdrequired
      - tagsstring[]
      - weightWeight
        Description
        Defines a common structure for representing weights.
        valuenumber<double>required
        Format
        double
        Minimum
        0
        unitstring<g | kg | lb>required
        Description
        Unit of measurement.
        Allowed
        gkglb
      - upcstring
      - feeMultiplierinteger<int32>
        Format
        int32
      - skuDimensionsDimensionsInfo[]
        Description
        This is a common definition of a sku's dimension.
        namestringrequired
        descriptionstring
        widthnumber<double>required
        Example
        18.5
        Format
        double
        lengthnumber<double>required
        Example
        18.5
        Format
        double
        heightnumber<double>required
        Example
        18.5
        Format
        double
        unitstring<cm | m | in | mm>required
        Allowed
        cmminmm
    - ProtectionPlanItemSummary
      - descriptionstringrequired
      - disabledbooleanrequired
      - namestringrequired
      - purchasablebooleanrequired
      - skuIdstringrequired
      - dynamicPropertiesobject
      - pricingPricing
        currencystringrequired
        Example
        USD
        Pattern
        ^[A-Z]{3}$
        pricenumberrequired
      - typestring<bundle | product | protectionPlan | service | warranty | fee>required
        Default
        protectionPlan
        Allowed
        bundleproductprotectionPlanservicewarrantyfee
      - termsAndConditionsTermsAndConditionsrequired
        UrlTermsAndConditions
        Max depth limit reached
        DrupalTermsAndConditions
        Max depth limit reached
        CloudinaryAssetUpdate
        Max depth limit reached
    - ServiceItemSummary
      - descriptionstringrequired
      - disabledboolean
        Default
        false
      - dynamicPropertiesobject
      - namestringrequired
      - pricingPricing
        Max depth limit reached
      - purchasablebooleanrequired
        Default
        true
      - skuIdSkuItemIdrequired
        Max depth limit reached
      - termsAndConditionsGeneralTermsAndConditions
        DrupalTermsAndConditionsUpdate
        Max depth limit reached
        CloudinaryAssetUpdate
        Max depth limit reached
      - typestring<product | protectionPlan | service | warranty>required
        Default
        service
        Allowed
        productprotectionPlanservicewarranty
    - WarrantyItemSummary
      - Max depth limit reached

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

ValidationErrorResponse
- namestringrequired
- codestringrequired
- detailstring

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

ErrorResponse
- namestringrequired
- codestringrequired
- detailstringrequired
- reasonstring

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

ErrorResponse
- namestringrequired
- codestringrequired
- detailstringrequired
- reasonstring

502

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

ErrorResponse
- namestringrequired
- codestringrequired
- detailstringrequired
- reasonstring

curl

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'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");
myHeaders.append("x-upstart-tenant", "string");
myHeaders.append("x-upstart-site", "string");

var requestOptions = {
   method: 'GET',
   headers: myHeaders,
   redirect: 'follow'
};

fetch("https://api.upstartcommerce.com/v1/catalog/live/recommendation/variant/{skuId}", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.upstartcommerce.com/v1/catalog/live/recommendation/variant/{skuId}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request["x-upstart-tenant"] = "string"
request["x-upstart-site"] = "string"

response = https.request(request)
puts response.read_body

python

import requests
import json

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

payload = {}
headers = {
   'accept': 'application/json',
   'content-type': 'application/json',
   'x-upstart-tenant': 'string',
   'x-upstart-site': 'string'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

200

// Success - recommendations holds the recommended variants and may be empty.
{
  "skuId": "",
  "customerId": "",
  "recommendations": [
    {
      "skuId": "",
      "score": "",
      "catalogItemId": "",
      "sku": {}
    }
  ]
}

400

// The request contained information that the server was unable to process. Appropriate errors are provided in the response body.
{
  "name": "",
  "code": "",
  "detail": ""
}

401

// The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.
{
  "name": "",
  "code": "",
  "detail": "",
  "reason": ""
}

404

// The requested resource was not found in the NoChannel system.
{
  "name": "",
  "code": "",
  "detail": "",
  "reason": ""
}

502

// An upstream service this endpoint depends on was unavailable, timed out, or returned an unusable response.
{
  "name": "",
  "code": "",
  "detail": "",
  "reason": ""
}