Product Recommendation Requests

Once the ML model is ready, you must create a serving configuration for each unique place where you want to provide your shoppers with product recommendations.

Serving configurations are how you define which ML model you want to use when requesting product recommendations. The process starts by creating your serving configuration in the GCP console (opens in a new tab), which includes information on which model you want to use and a few other settings.

Then, when you request product recommendations, you will specify the serving configuration ID, which is how you define which model you want to use when requesting product recommendations.

We recommend a unique serving configuration for each placement + ML model type. A "placement" is where you will provide your shoppers's recommendations on your website.

By using serving configurations, you can save on model training costs. For example, you may want to showcase a “Recommended for you” recommendation on your home and product detail pages. Rather than creating two different ML models for each placement, you can create a single ML model for "Recommended for you" and then create two different serving configurations for each placement. The model will be able to understand that there are two placements using the serving configurations and adjust its recommendations based on each unique placement.

After you have the serving configuration(s) set up, you will make a request to the GraphQL Storefront API each time you render a page. The API returns a recommendation specific to the shopper at that moment in time in the response body.

Here are the flow of events:

You send a request to BigCommerce's GraphQL Storefront API for recommendations. You include the product details you want the shopper to see with each recommendation. BigCommerce sends a request to Google Vertex AI, including the shopper session ID, which we automatically extract from browser cookies.
Google Vertex AI responds with a list of product IDs for each request and an attribution token (opens in a new tab). BigCommerce receives the list of product IDs.
BigCommerce uses the product IDs to find additional product details, such as name, price, and description, before sending the product recommendation back to you in the response.

Technical Design Considerations:

The latency of Google Vertex AI ranges from 100 to 400 ms. We strongly recommend that you refrain from combining your recommendation requests with other GraphQL Storefront API requests.
Depending on the request's complexity score, the API returns five to fifteen recommended products.
You don't need to send pagination information. Google does not support pagination for this endpoint.
After you make a recommendation request, BigCommerce includes an attribution token (opens in a new tab) in product and cart URLs returned in GraphQL responses to help tune model performance. If you use custom URLs, we highly recommend including the attribution tokens in your URLs. This feature helps identify which recommendations led to particular outcomes to improve model performance.

Filtering products

You can narrow your prediction results by specifying filter criteria in your GraphQL Storefront API requests. BigCommerce passes the criteria to Google Vertex AI to use Google's filtered recommendations (opens in a new tab). Google Vertex AI will then handle the filtering when responding with the list of recommended products. The options for filtering are based on the catalog data sent to Google.

Products marked not visible on your storefront

By default, products marked as "not visible" on your BigCommerce catalog's storefront will not appear in product recommendations. This is achieved by three pieces working together:

The products are marked as "not visible" in your catalog, and Google has up-to-date information (we update the information every 6 hours).
In the GCP console, the "attribute.visibility" needs to be filterable. This is set to filterable by default.
When you create an ML model, the model needs to be set to filterable. This is true by default. If you change this setting, then products marked as not visible on the storefront might show up in your product recommendations as they are not being filtered out.
When you make a product recommendation request using GQL, we automatically add the filter to filter out products that are not visible on your storefront. You don't need to add code to filter out products that are not visible on the storefront in your GQL code.

Required setup to filter on one or more product attributes

If you want to filter on other product attributes when getting product recommendations, you will need to make sure the following settings are set up correctly:

Ensure the attribute you want to filter on is configured to be filterable. This can be found in "GCP > Search for Retail > Controls > Attribute Controls > Modify Controls", where you want to set this to "True" for the "Filterable" column.
In GCP, make sure your ML model has the "Filter setting" set to "enabled".
Any changes to your catalog are updated in Google every 6 hours.
If you change these settings, you may need to wait 12 hours to a couple of days to see the results reflected in the recommendation requests, as the models will need to learn about these new conditions.

Benefits

Retrieving recommendations through BigCommerce's GraphQL Storefront API has the following benefits:

You can continue authenticating your requests through the GraphQL Storefront API without additional authentication through Google.
You only need one API request to retrieve all the information you want to render for the recommended products. When you query recommendations through the GraphQL Storefront API, the response includes all the desired details about the products, not just the product IDs returned from Google.

Example use-cases and placements

You can incorporate product recommendations anywhere on your website where you have the ability to modify your theme to utilize the GQL Storefront API.

The following example requests product recommendations from BigCommerce. For information on authentication, see the Authenticating Requests to the GraphQL Storefront API article. To see how to modify your Stencil theme, see the reference code for Cornerstone (opens in a new tab).

You can test the model with arbitrary data without affecting live data or impacting the model's performance. To do so, use the validateOnly flag, as shown in the following example.

Example request

query ($pageSize: Int = 3) {
  site {
    apiExtensions {
      googleAiPrediction (
          pageSize: $pageSize
          userEvent: {eventType: "detail-page-view", productDetails: [{entityId: 77, count: 1}]}
          servingConfigId: "your_serving_config_id"
          validateOnly: true # for testing the model
          filter: "categories: ANY(\“shoes\”,\”pants\”)"
        ) {
        results {
          entityId
          name
        }
      }
    }
  }
}

If a store has cookie tracking consent enabled, the shopper must provide consent to advertising for you to use Google Vertex AI. This consent ensures that BigCommerce complies with user consent preferences. For more information, see the Set cookie consent preferences endpoint.

If a store has cookie tracking consent enabled and a shopper doesn't provide consent, you'll receive an error message when requesting product recommendations for that shopper:

Error message

"data": null,
"errors": [
  {
    "message": "Shopper consent is required to use Google Retail API. Please provide consent to get personalized recommendations."
    // location of error ...  
  }
]

Did you find what you were looking for?

Getting started Machine learning models