> For a complete page index of the Captain API documentation, fetch https://docs.captain.dev/llms.txt?excludeSpec=true

# BigCommerce

> Sync your BigCommerce catalog into Captain Product Search and put Captain's search box on your storefront.

Connect a BigCommerce store, and Captain imports its visible products and the orders it needs to measure search revenue. Then put Captain's search box on the storefront with one snippet.

> **Note**
>
> The BigCommerce integration is in beta. Captain tested it end to end against a recorded copy of BigCommerce's documented API, not yet against a live store. Captain switches it on per tenant: ask the Captain team on Slack.

## Quick start

#### [1. Make an API account](#make-a-read-only-api-account)

Create a read-only store-level API account in BigCommerce.

#### [2. Connect](#connect-the-store)

Paste the store hash and access token into the Captain console.

#### [3. Turn on search](#turn-on-storefront-search)

Create a storefront key and add the snippet with Script Manager and Page Builder.

## How it works

* **The store connection** reads your catalog and orders with a read-only API account and keeps a Captain catalog in sync. It never changes anything in BigCommerce.
* **Live updates.** When you connect, Captain subscribes to BigCommerce's product and order webhooks. A change in the store starts an import of what changed within a few minutes.
* **The search box** is Captain's [search widget](/guides/product-search/search-widget). You add it to the storefront with Script Manager and a Page Builder HTML widget. It searches your Captain catalog with a public, scoped storefront key.

## Before you start

* A BigCommerce store, and a store owner or a user allowed to create API accounts.
* A Captain Product Search tenant with BigCommerce switched on.
* An owner of your Captain organization, to create the storefront key later.

## Make a read-only API account

### Open API accounts

In the BigCommerce control panel, open **Settings**, then **Store-level API accounts** (under **API**), and select **Create API account**.

### Choose the token type

Set **Token type** to **V2/V3 API token**, and name the account, for example `Captain search`.

### Set the scopes

Set these four to **read-only** and leave every other scope at **None**:

| Scope                      | Why Captain needs it                                                                                        |
| -------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Products**               | Import products, variants, images, brands, categories and custom fields, and subscribe to product webhooks. |
| **Orders**                 | Measure revenue from search, and subscribe to order webhooks.                                               |
| **Information & Settings** | Read the store's name, default currency and storefront address.                                             |
| **Store Inventory**        | Read stock levels.                                                                                          |

### Save and copy

Select **Save**. BigCommerce shows the credentials once. Copy the **Access token**, and the **API path**: `https://api.bigcommerce.com/stores/<store hash>/v3/`. The store hash is the part after `/stores/`.

## Connect the store

### Open the BigCommerce card

In the Captain console, open **Developers**, then **Integrations**. On the **BigCommerce** card, select **Connect**.

### Name the connection and the catalog

In **Name**, enter a name such as the store's name. In **New catalog name**, enter a name no other catalog uses, such as `bigcommerce-products`. Captain creates this catalog.

### Choose how often to resync

In **Sync every**, choose 1, 6, 12 or 24 hours.

### Paste the credentials

Paste the **Store hash** and the **Access token**, then select **Connect**.

Captain tests the token first. It reads the store, one product and one order, and refuses the connection in plain words if any of those fails. The token is kept in AWS Secrets Manager and never shown again, logged or sent to the browser.

The first import starts on its own. The connection shows its status, product and variant counts, and last sync.

## What syncs

### Products

Captain imports every product whose **Visible on storefront** setting is on. A hidden product stays out, and hiding one removes it at the next import.

Each variant is one record. A product with no options is one record (its base variant).

| BigCommerce field                                                                              | Captain field                                        |
| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `name`                                                                                         | `title`                                              |
| `description` (HTML removed)                                                                   | `body`                                               |
| brand name (`brand_id`)                                                                        | `vendor`                                             |
| category names (`categories`, from the category tree)                                          | `collections`                                        |
| `search_keywords` (comma separated)                                                            | `tags`                                               |
| `custom_url.url`                                                                               | `handle`, and `url` with the store's address         |
| images, thumbnail first (`url_standard`)                                                       | `images`, and `image` unless the variant has its own |
| variant option values (`option_display_name`: `label`)                                         | `options`, `option_values`, `variant_title`          |
| variant `sku`                                                                                  | `sku`                                                |
| variant or product `upc`, then `gtin`                                                          | `barcode`                                            |
| variant `calculated_price`                                                                     | `price`                                              |
| the regular `price` during a sale, otherwise `retail_price` when higher                        | `compare_at_price`                                   |
| `inventory_level` (per variant or product, by `inventory_tracking`)                            | `inventory`                                          |
| in stock, not purchasing-disabled, and `availability` not `disabled`                           | `available`                                          |
| `date_created`, `date_modified`                                                                | `created_at`, `updated_at`                           |
| `condition`, `type`, `mpn`, `gtin`, `upc`, `weight`, `availability`, `warranty`, custom fields | `attributes`                                         |

Prices are in the store's default currency. A product whose availability is **Disabled** stays searchable but shows as unavailable, as it does on the storefront.

### Orders

Captain reads orders by when they last changed, so an order paid later is counted when it's paid. It records one purchase event per revenue order: the variants, quantities and prices excluding tax, the subtotal excluding tax, and the currency.

Revenue orders have these statuses: Awaiting Fulfillment, Awaiting Shipment, Awaiting Pickup, Partially Shipped, Shipped, Completed and Partially Refunded. Pending, Awaiting Payment, Incomplete, Declined, Cancelled, Refunded, Disputed and Manual Verification Required orders count zero. Captain stores no customer names, emails or addresses.

## Live updates

When you connect, Captain subscribes the store to these webhooks: product created, updated and deleted, product inventory updated, order created and order status updated. Each one starts an import of what changed within a few minutes. The **Live updates** panel on the connection says when the store last reported a change.

* A product deleted in BigCommerce leaves the catalog at the next daily full import, or right away with **Sync now**.
* BigCommerce doesn't change a product's modified date when stock changes through its Inventory API. Captain still re-reads stock at the daily full import and on **Sync now**.
* Disconnecting removes the webhook subscriptions.

## Turn on storefront search

### Create a storefront key

Open the BigCommerce connection's **Manage** panel. Under **Storefront search**, add your storefront's domains if they aren't already listed, and select **Create storefront key**. The panel shows a snippet with the key filled in, once. Copy it.

The key is public: it only searches this catalog, only from your store's addresses.

```html
<script type="module"
  src="https://cdn.jsdelivr.net/gh/runcaptain/captain-search@1.8.0/captain-search.js"
  integrity="sha384-JE4C0r/iXcnqRePQ+XK/wsFWEWRqxIR8gTfYjlnOTnd2gUaq+Y+BYHC/IRNFy/xp"
  crossorigin="anonymous"></script>

<captain-search
  endpoint="https://acme.captain.dev"
  index="bigcommerce-products"
  key="YOUR_SCOPED_KEY"
  placeholder="Search products"
></captain-search>
```

### Add it to the storefront

### Load the script on every page

In BigCommerce, open **Storefront**, then **Script Manager**, and select **Create a Script**. Name it `Captain search`. Set **Location** to **Head**, **Select pages where script will be added** to **All pages**, **Script category** to **Essential** and **Script type** to **Script**. Paste the first part of the snippet (the `<script>` tag) and save.

### Place the search box

Open **Storefront**, **My Themes**, and **Customize** to open Page Builder. Drag an **HTML** widget where the search box belongs, such as a header region, and paste the `<captain-search>` element. Your theme decides which regions Page Builder offers.

### Publish and test

Select **Publish**, then search on the storefront in a private window.

The widget's [settings](/guides/product-search/search-widget) change its look and what each result shows.

## Sync now and Disconnect

* **Sync now** starts a full import at any time. It also removes products the store no longer has.
* **Disconnect** stops syncing, removes the webhook subscriptions and deletes the stored token. The catalog stays until you delete it. To revoke the token in BigCommerce too, delete the API account under **Store-level API accounts**.

## Troubleshooting

#### BigCommerce refused the credentials

The token is wrong, revoked, or its account lacks a scope. Check that Products, Orders, Information & Settings and Store Inventory are read-only on the API account, and that the store hash is the one in its API path.

#### A product is missing

Check that **Visible on storefront** is on for it. Then select **Sync now** and search again after the sync finishes.

#### Stock looks out of date

A stock change made through BigCommerce's Inventory API reaches Captain at the next daily full import. Select **Sync now** to read it right away.

#### BigCommerce is rate limiting Captain

Every app on a store shares one request quota. Captain waits out BigCommerce's limit and leaves some requests for your other apps, so a large first import can take longer. The sync continues on its own.

#### The search box doesn't appear

Check that the Script Manager script is on **All pages**, that your theme renders scripts in the head, and that the HTML widget is published. A `403` from Captain in the browser's network tab means the storefront key doesn't list this domain: create a new key with every storefront domain.