Beta Programs
Product Recommendations
GraphQL Storefront API
Schema

Requesting Recommendations Reference

The following schemas describe the Product Recommendations feature of the GraphQL Storefront API (opens in a new tab).

Query

type Query {
  "Represents a site."  
  site: Site!
 
  # ... for full schema, see https://developer.bigcommerce.com/graphql-storefront/reference#query-site
 
}

Types

type Site {
  "Access to BigCommerce API extensions."
  apiExtensions: ApiExtensionsQueries!
 
  # ... for full schema, see https://developer.bigcommerce.com/graphql-storefront/reference#definition-Site
 
}
 
"This set of queries allows for extending the API's capabilities, including integrating with external services like Google's Vertex AI for predictive modeling based on user events."
type ApiExtensionsQueries {
  "Google Vertex AI Prediction: Leverages Google Cloud's Vertex AI to predict product recommendations based on user activities. This prediction is facilitated by Google's machine learning models, which analyze user event data to suggest relevant products from a catalog. Reference: https://cloud.google.com/retail/docs/reference/rest/v2beta/projects.locations.catalogs.servingConfigs/predict"
  googleAiPrediction (
    "Unique identifier for the ServingConfig resource. This ID is mandatory for the Predict method, as it specifies the serving configuration used to process the prediction."
    servingConfigId: String!,
 
    "Represents the user's interaction with the website or application, such as views, clicks, or purchases. This input is critical for tailoring the prediction to reflect the user's preferences and recent activities."
    userEvent: UserEventInput!,
 
    "Specifies the maximum number of prediction results to return. This limit allows for control over the volume of suggested products. The maximum allowed value is 15, ensuring a focused set of recommendations."
    pageSize: Int!,
 
    "A string parameter to narrow down prediction results based on specific criteria, such as product tags or attributes. This filter uses the syntax of Google Vertex AI, allowing for complex queries to refine the product recommendations."
    filter: String,
 
    "When set to true, the query operates in a test mode using a dummy model. This model returns arbitrary products, enabling developers to validate the query structure and execution without affecting live data or impacting the model's performance. The default value is false."
    validateOnly: Boolean,
 
    "Additional parameters specific to the retail domain that can influence the prediction outcome. These might include customization options that tailor the prediction results more closely to business needs or user preferences."
    params: RetailAiInput): GoogleAiPrediction! 
}
 
"Response from Google Vertex AI prediction. Reference: https://cloud.google.com/retail/docs/reference/rest/v2beta/PredictResponse"
type GoogleAiPrediction { 
  "A list of recommended products, ordered from most to least relevant product."
  results: [Product!]!
 
  "A unique attribution token. See https://cloud.google.com/retail/docs/attribution-tokens"
  attributionToken: String!
 
  "IDs of products in the request that were missing from the inventory."
  missingEntityIds: [String!]!
 
  "Indicates if the request was made for validation purposes only."
  validateOnly: Boolean!
}
 
"Details of a product."
type Product {
  # For the full schema, see https://developer.bigcommerce.com/graphql-storefront/reference#definition-Product 
}

Inputs

"Input for product details."
input ProductDetailsInput {
  "Product ID."
  entityId: Int!
 
  "Quantity of the product."
  count: Int!
}
 
"Input for Vertex AI."
input RetailAiInput {
  "If set to false, the service returns unfiltered popular products when predictions are blocked."
  strictFiltering: Boolean
 
  "Adjusts prediction results based on product price. Options: 'no-price-reranking', 'low-price-reranking', 'medium-price-reranking', 'high-price-reranking'."
  priceRerankLevel: String
 
  "Adjusts prediction results based on product category. Options: 'no-diversity', 'low-diversity', 'medium-diversity', 'high-diversity', 'auto-diversity'. Reference: https://cloud.google.com/retail/docs/configs#diversification"
  diversityLevel: String
 
  "if set to true, interprets the filter field according to the new attribute-based syntax."
  filterSyntaxV2: Boolean 
}
 
 
"Input for user events."
input UserEventInput {
  "Type of the event. For a list of all user events, see https://cloud.google.com/retail/docs/user-events#types."
  eventType: String!
 
  "Details of the products involved in the event."
  productDetails: [ProductDetailsInput!]!
}
Did you find what you were looking for?