Skip to main content

BigCommerce Connector

The BigCommerce connector links one BigCommerce store to one eshopOS store and uses that link for preview and import jobs.

This is a migration workspace, not a generic API client and not a permanent storefront sync layer.

Connection Methods​

The BigCommerce connector supports two connection methods.

1. API credentials​

This is the recommended merchant path right now.

Use this method when:

  • you want the fastest setup
  • your BigCommerce app is not fully configured yet
  • you already have a store-level API account

The merchant enters:

  • the BigCommerce Management API path
  • the store access token

2. BigCommerce app connection​

This method uses the BigCommerce app install and authorization flow.

Use this when:

  • the eshopOS BigCommerce app is already configured for your environment
  • you want the merchant to approve access without pasting a token manually

The merchant does not enter:

  • client_id
  • client_secret
  • callback URLs

Those are platform app settings handled by the eshopOS operator, not merchant inputs.

Until the BigCommerce app rollout is fully configured for your environment, use API credentials on the connector page.

API credentials and app connection both let eshopOS do the same import work:

  • preview catalog and inventory data
  • import products and categories
  • create or match warehouses
  • import inventory levels

The difference is mainly how the external access is granted.

What the Connector Imports​

The current BigCommerce path is designed around core commerce migration:

  • products
  • categories
  • variants
  • product images
  • inventory locations
  • location stock levels

What the Connector Does Not Import Yet​

Current non-goals:

  • orders
  • coupons and promotion logic
  • storefront theme behavior
  • modifier-heavy product customization
  • metafields as first-class eshopOS fields
  • customer import
  • continuous real-time sync

What You Need Before Connecting​

If you are using API credentials​

You need:

  • a BigCommerce store
  • a BigCommerce store-level API account
  • the store API path
  • the store access token

If you are using the app connection​

You need:

  • a BigCommerce store
  • permission to install or approve apps for that store
  • an eshopOS environment where the BigCommerce app has already been configured

You do not need to create your own client ID or client secret as a merchant.

Where to Get the API Path and Access Token​

In BigCommerce Admin:

  1. Open Settings.
  2. Open API accounts.
  3. Create or open a Store-level API account.
  4. Copy the access token when BigCommerce shows it.
  5. Use your store hash to build the API path.

The API path format is:

https://api.bigcommerce.com/stores/STORE_HASH/v3/

Example:

https://api.bigcommerce.com/stores/abc123/v3/

Important:

  • the token is shown by BigCommerce at creation time and should be stored securely
  • the token is a merchant store secret
  • do not paste any platform app secret into the connector form

Official reference:

Merchant Setup Flow​

API credentials flow​

  1. Open Connectors.
  2. Open the BigCommerce workspace.
  3. Paste the API path.
  4. Paste the Access token.
  5. Click Connect with API credentials.
  6. Confirm the linked store shown in the workspace.
  7. Run Preview before a full import.

App connection flow​

  1. Open Connectors.
  2. Open the BigCommerce workspace.
  3. Click Connect with app.
  4. Approve the install in BigCommerce.
  5. Return to eshopOS.
  6. Confirm the linked store shown in the workspace.
  7. Run Preview before a full import.

App Setup Note​

If you are using app connection, the app credentials and callback URLs are configured centrally by the eshopOS operator.

Merchants should not enter:

  • app client IDs
  • app client secrets
  • callback URLs

Merchants only approve the app install flow.

Credential Fields​

API path​

The connector expects the BigCommerce Management API base path for the store.

Required shape:

https://api.bigcommerce.com/stores/STORE_HASH/v3/

Access token​

The connector uses the BigCommerce store access token for authenticated catalog and inventory requests.

The token is stored on the backend. It is not returned to the dashboard UI after connection.

Data Mapping​

The BigCommerce connector normalizes provider data into eshopOS core records instead of writing BigCommerce-native structures into the storefront model.

Catalog Mapping​

BigCommerce fieldeshopOS target
nameproduct name
custom_url.urlproduct slug
descriptionproduct description
product/variant priceproduct + variant price
sale pricecompare_price / selling-price derivation
image URLsproduct images
category IDsproduct category slugs
variant option labelsvariant title
variant SKUvariant sku

Inventory Mapping​

BigCommerce fieldeshopOS target
inventory locationswarehouses
location inventory item countslocation stock records
variant inventory referencesimported variant links

Storefront Compatibility​

BigCommerce data is compatible with the eshopOS storefront because the connector writes into eshopOS core models first.

That means:

  • the storefront reads eshopOS products, not BigCommerce products
  • publish state is controlled by eshopOS product rules
  • category browsing uses eshopOS category slugs
  • warehouse stock uses eshopOS inventory tables

Preview Behavior​

Preview is a read-only inspection step.

Use it to verify:

  • expected product counts
  • category detection
  • whether locations are visible
  • whether inventory rows are available
  • whether the connector plans to create or update records
  • any warnings returned during data fetch

Import Behavior​

When the merchant runs a BigCommerce import:

  • products are created or updated in the current eshopOS store
  • categories are created or reused as eshopOS categories
  • variants are written into the eshopOS structured variant model
  • warehouses are created or matched from BigCommerce locations
  • location stock is set against eshopOS warehouse inventory

Reruns are expected to reconcile against existing mappings rather than duplicate every record.

Security Notes​

Treat BigCommerce credentials as sensitive:

  • do not commit them to the repo
  • do not log them in plain text
  • do not expose them in browser responses
  • rotate them if they are pasted into chat, screenshots, or shared docs

Store-level access tokens do not behave like short-lived browser session tokens. Handle them as durable backend secrets.

Common Failure Cases​

Invalid API path​

Symptoms:

  • connection fails immediately
  • preview returns provider request errors

Check:

  • the path includes the correct store hash
  • the path uses the Management API base path
  • the path ends at /v3/ or a trim-equivalent form

Invalid or revoked token​

Symptoms:

  • connection or preview returns unauthorized errors
  • previously working imports stop loading

Check:

  • the token still exists in BigCommerce
  • the API account was not deleted
  • the token has the scopes needed for catalog and inventory reads

App connection opens but does not return to eshopOS​

Check:

  • the BigCommerce app Auth callback URL
  • the BigCommerce app Load URL
  • whether the eshopOS environment has the correct app credentials configured

Products load but location stock is missing​

Symptoms:

  • preview shows products
  • locations or inventory counts are empty

Check:

  • whether the store uses multiple inventory locations
  • whether the API account can read inventory-related resources
  • whether BigCommerce returned location warnings during preview

Readiness Checklist​

Before using the connector for a real merchant store, confirm:

  • connection succeeds with the intended store
  • preview loads products and categories
  • variants land in the eshopOS variant model
  • warehouses are created or matched correctly
  • location stock appears against the correct warehouses
  • reruns update mapped records rather than duplicating them
  • warnings are visible in preview and run history