Getting Started

This guide describes the steps to help you get ready to request product recommendations through the BigCommerce GraphQL Storefront API.

Steps to set up and use this integration

Step 1: Set up a Google Cloud account (opens in a new tab), a Google Cloud project (opens in a new tab), and turn on billing (opens in a new tab).
Step 2: Provide BigCommerce access to your Google Cloud project.
Step 3: Turn on the integration to load data into your GCP account.
Step 4: Configure your Machine Learning Models in GCP.
Step 5: Create serving configurations and model placements.
Step 6: Integrate the GraphQL Storefront API into your storefront to get recommendation requests.
Step 7: Measure the effectiveness of your recommendations.

Step 1: Set up a Google Cloud account and a Google Cloud Project

Set up a Google Cloud account (opens in a new tab) and a Google Cloud project (opens in a new tab).

In your Google Cloud Platform console, you will need set up Vertex AI Search for Retail. To do so, navigate to “Search for Retail“ in your Google Cloud Platform console and click on “Turn on API”. For more detailed steps, see the Set up Vertex AI Search for retail (opens in a new tab) guide in the Google documentation.

Step 2: Grant BigCommerce access to your GCP Project

Grant BigCommerce access to the Google Cloud project in your Google Cloud account. Add Retail Editor (opens in a new tab) and Retail Service Agent (opens in a new tab) role permissions to BigCommerce Data Team's GCP Service Account, bigcommerce-prod-rec@bc-data-production.iam.gserviceaccount.com.

Step 3: Turn on the integration to load data into GCP

To turn on this integration, send a request to the Google Vertex AI endpoint of the REST Management API with the project ID (opens in a new tab). Immediately after you complete this step, we will start loading data into your GCP account.

💡

Each channel can only have one integration setup. BigCommerce only loads data from the channel you specify when you send an integration request.

BigCommerce authentication

Authenticating requests requires a store-level API Account with an access token that has the following OAuth Scope:

UI name	Permission	Parameter	Description
Information & Settings	modify	`store_v2_information`	View and modify store information and settings.

For more information on access token authentication, see Authentication and Example Requests.

Example requests

The following example turns on the integration to connect to your GCP account.

Example request: Create a connection

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/data-solutions/google-ai
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
 
{
  "project_id": "your_product_id",
  "channel_id": 1
}

The following example turns off the integration so that BigCommerce stops loading data into your GCP account.

Example request: Delete a connection

DELETE https://api.bigcommerce.com/stores/{{store_hash}}/v3/data-solutions/google-ai
X-Auth-Token: {{access_token}}
Accept: application/json
 
{
    "channel_id": 1
}

Step 4: Configure your Machine Learning Models in GCP

Before you start model configuration, make sure your historical data is loaded. You can view whether there is enough data to start training the models in the Google Cloud console (opens in a new tab).

Once your historical data is loaded, you can configure your product recommendation ML models in GCP.

Create the recommendation model (opens in a new tab)
Create serving configurations (opens in a new tab) and model placements

Step 5: Create serving configurations and model placements

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.

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.

Step 6: Integrate the GraphQL Storefront API into your storefront to get recommendation requests

When you send a request to the GraphQL Storefront API, BigCommerce sends a request to Google's Vertex AI for product recommendations. BigCommerce receives product IDs from Google, which are used to fetch product information to include in the GraphQL Storefront API response.

Here you'll find the details on how to make a recommendation request.

Step 7: Measure the effectiveness of your recommendations

In your GCP account, you can view analytic metrics (opens in a new tab) on Clickthrough Rate (CTR), Conversion Rate (CVR), and Average Order Value (AOV) to gauge the model's performance.

Resources

Did you find what you were looking for?

Overview Request product recommendations