BigCommerce | Captain

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.

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

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

2. Connect

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

3. Turn on 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. 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.

<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.

Publish and test

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

The widget’s settings 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.