> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# 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](https://cloud.google.com/vertex-ai/docs/tutorials/tabular-bq-prediction/prerequisites#create-account), a [Google Cloud project](https://cloud.google.com/vertex-ai/docs/tutorials/tabular-bq-prediction/prerequisites#create-project), and [turn on billing](https://cloud.google.com/billing/docs/how-to/modify-project).
* 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](/developer/docs/beta/product-recommendations/request-recommendations).
* 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](https://cloud.google.com/vertex-ai/docs/tutorials/tabular-bq-prediction/prerequisites#create-account) and a [Google Cloud project](https://cloud.google.com/vertex-ai/docs/tutorials/tabular-bq-prediction/prerequisites#create-project).

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](https://cloud.google.com/retail/docs/setting-up#setup-project) 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](https://cloud.google.com/retail/docs/iam) and [Retail Service Agent](https://cloud.google.com/iam/docs/create-service-agents) 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](/developer/docs/beta/product-recommendations/api-reference) endpoint of the REST Management API with the [project ID](https://cloud.google.com/vertex-ai/docs/tutorials/tabular-bq-prediction/prerequisites#find-project-id). Immediately after you complete this step, we will start loading data into your GCP account.

> **Note**
>
> 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](/developer/docs/overview/api-fundamentals/api-accounts#store-level-api-accounts) with an access token that has the following [OAuth Scope](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes):

| 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](/developer/docs/overview/api-fundamentals/api-accounts#access-tokens).

### Example requests

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

#### Request

**`Example request: Create a connection`**

```http title="Example request: Create a connection" showLineNumbers={false}
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
}
```

#### Response

**`Example response: Create a connection`**

```http title="Example response: Create a connection" showLineNumbers={false}
HTTP 200 No content
```

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

#### Request

**`Example request: Delete a connection`**

```http title="Example request: Delete a connection" showLineNumbers={false}
DELETE https://api.bigcommerce.com/stores/{{store_hash}}/v3/data-solutions/google-ai
X-Auth-Token: {{access_token}}
Accept: application/json

{
    "channel_id": 1
}
```

#### Response

**`Example response: Delete a connection`**

```http title="Example response: Delete a connection" showLineNumbers={false}
HTTP 200 No content
```

## 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](https://cloud.google.com/retail/docs/manage-user-events#view-events).

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

* [Create the recommendation model](https://cloud.google.com/retail/docs/create-models)
* [Create serving configurations](https://cloud.google.com/retail/docs/create-configs) 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](https://cloud.google.com/retail/docs/create-configs), 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](/developer/docs/beta/product-recommendations/request-recommendations).

## Step 7: Measure the effectiveness of your recommendations

In your GCP account, you can [view analytic metrics](https://cloud.google.com/retail/docs/metrics) on Clickthrough Rate (CTR), Conversion Rate (CVR), and Average Order Value (AOV) to gauge the model's performance.

## Resources

* [Product recommendations overview](/developer/docs/beta/product-recommendations/overview)
* [Google Vertex AI Prerequisites (Google documentation)](https://cloud.google.com/vertex-ai/docs/tutorials/tabular-bq-prediction/prerequisites)
* [Store-level API Account](/developer/docs/overview/api-fundamentals/api-accounts#store-level-api-accounts)
* [OAuth Scopes](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes)
* [Authentication and Example Requests- Access tokens](/developer/docs/overview/api-fundamentals/api-accounts)
* [Google Vertex AI](/developer/docs/beta/product-recommendations/api-reference) endpoint for REST Management API
* [Create recommendation models (Google documentation)](https://cloud.google.com/retail/docs/create-models)
* [Create serving configurations](https://cloud.google.com/retail/docs/create-configs)