# Configuration

# Create an API Account

  1. Log in to the BigCommerce instance and go to Advanced Settings → API Accounts, click on the Create API Account CTA and select Create V2/V3 API Token

Create API account

  1. Create a name for the API Account
  2. Copy the API Path
  3. Set all OAuth Scopes to (give full scope):
OAuth Scope Access level
Content Modify
Checkout Content Modify
Customers Modify
Customers Login Login
Information & Settings Modify
Marketing Modify
Orders Modify
Order Transactions Modify
Create Payments Modify
Get Payment Methods Read-Only
Stored Payment Instruments Modify
Products Modify
Themes Modify
Carts Modify
Checkouts Modify
Sites & Routes Modify
Channel Settings Modify
Channel Listings Modify
Storefront API Tokens Manage
Storefront API Customer Impersonation Tokens Manage
  1. Once the account has been created, a file containing BigCommerce API Credentials should automatically be downloaded. These are the same credentials that appear after creating the API account.

# Create a new BigCommerce App

  1. Go to https://devtools.bigcommerce.com/my/apps (opens new window) and login under your account
  2. Click on Create an app, set a name, e.g. VueStorefront, and close the pop up window
  3. You should see the app appear in the list, click on View Client ID and take note of the Client ID and the Client Secret

My apps

# Create a new Channel

“A channel is anywhere a merchant sells their products. This encompasses headless storefronts, marketplaces, POS systems, and marketing platforms.” - Reference - Channels - Management APIs - API Reference (opens new window)

The following steps will be referenced from the BigCommerce website. The steps can be done by sending POST request through the command line / Postman, or BigCommerce website itself.

  1. Open Create a Channel - Channels - Channels - Management APIs - API Reference (opens new window) and scroll down to Send a test Request.
  2. Populate the store_hash with your personal hash, this can be found as a part of the API Path URL from the previous step. e.g.: https://api.bigcommerce.com/stores/noq5tdq0k6/v3/ (opens new window) (the part between /stores/ and /v3/)
  3. Populate X-Auth-Token with your BigCommerce API Access Token from the step above.

New channel

  1. Go to the Body section of the Test Request tool set the following payload
  "name": "VueStorefront",
  "platform": "custom",
  "type": "storefront",
  "status": "active"

New channel request)

  1. The response will contain an id which we will be used as the channel_id in next requests, keep a note of it.

# Create a Channel Site

  1. Go to Create a Channel Site - Channel Site - Channels - Management APIs - API Reference (opens new window)
  2. Set the channel_id from the Create Channel response in Path Params

Channel site

  1. Go to the Body tab and set the url as the link where the VueStorefront + BigCommerce app will be hosted, together with the channel_id from the previous step
  "url": "http://myvuestorefrontbigcommerce.com",
  "channel_id": 920506

Channel site request

# Create a Route for the Cart

To ensure Edit Cart Link in Embedded Checkout is not pointing to original storefront.

  1. Open the BigCommerce admin panel
  2. Go to the Channel Manager
  3. Select the Channel you have just created and click on Advanced Settings
  4. Scroll down to Site details and copy the Site ID

Site ID

  1. Go to Create a Site Route - Site Routes - Sites - Management APIs - API Reference (opens new window)
  2. Copy the Site ID in the Test Request Settings field

Create site

  1. Open the Body tab in Send Request and paste the following payload:
  "type": "cart",
  "matching": "*",
  "route": "/"
  1. Once successful, repeat the operation with a different payload:
  "type": "home",
  "matching": "*",
  "route": "/"
  1. Once successful, repeat the operation with a different payload again:
  "type": "create_account",
  "matching": "*",
  "route": "/"
  1. Once successful, repeat the operation with a different payload once more:
  "type": "forgot_password",
  "matching": "*",
  "route": "/"

Create site request

  1. Click on Send

Please note that this step is important to alter those routes for Edit Cart, Register and Create password links on checkout otherwise it will be pointing to the Default Store front of BigCommerce.

The route can be changed for custom page later on if those pages will be created in the integration, currently create_account is in a modal and forgot_password is non existent.

At the time of writing this guide (31/01/2021) it was not possible to create the route via admin panel, this might be fixed in the future by the BigCommerce team.

# Create a custom Cart ID field on Customers entity

  1. Login to your BigCommerce back office, and go to Advanced Settings → Customer Sign Up Form
  2. Click on Create a New Field and select Text Field

Custom cart id field

  1. Set the Field name to: Cart ID

  2. Leave all other fields with the default values and press Save

Custom cart id field setup

# Storefront URL and Guest Token

  • Login to your BigCommerce back office, and go to the Dashboard (main page).

# Storefront URL

# Guest Token

  • If your store isn’t published find the Review & Test your store tab, and copy the Guest Token, it will be needed in the environment variables
  • If the store is published the guest token step might be ignored

Guest token

# Host BigCommerce Storefront on a subdomain

Ensure that the BigCommerce Storefront is hosted on a subdomain of the application.

This will be required to make the embedded checkout work.

BigCommerce prepared a guide how to change the domain of the store

BigCommerce Help Center (opens new window)

BigCommerce consultants suggests to create a CNAME pointing to BigCommerce instance. It should be hosted on the same server that the VSF app.


When the CNAME like https://www.checkout.mystore.com (opens new window) is created, it can be added as a new domain.

  1. Navigate to Server Settings → Domain name.

Server settings

Only the store owner can access the page and add a new domain.

  1. Select Add an existing option.

Add domain

  1. Enter domain name and extension.

Domain URL

  1. That’s all. Now the domain is added and BigCommerce store is available on this domain. BigCommerce should automatically add a SSL certificate.

  2. To check the status of SSL certificate navigate to Server Settings → SSL Certificates

Only the store owner can access the page and manage SSL certificates.

# Additional changes

  • It is possible to add more address or customer fields in BigCommerce, as well as making particular fields as ‘required’

  • To add a new field - open the BigCommerce Admin panel

    1. Go to Advanced Settings > Account Signup Form

    2. Here you can select Account Signup Fields or Address Fields to create or amend the existing fields

    3. Please note that Address Fields will be reflected on the embedded checkout automatically

    4. Any new created or edited fields will need to be matched in one of the following components:

    • packages/theme/components/MyAccount/ShippingAddressForm.vue - for address fields

    • packages/theme/components/LoginModal.vue - for customer fields in the registration form

    • packages/theme/components/MyAccount/ProfileUpdateForm.vue - for customer fields in the update form

Additional fields

# Set up VueStorefront

The BigCommerce instance is now ready for VueStorefront! Let’s set up our codebase.

  1. Clone the repository: GitHub - vuestorefront/bigcommerce (opens new window)
  2. Rename .env.example to .env and change the file content with the following
BIGCOMMERCE_API_ACCESS_TOKEN={Access Token from Step 1 }
BIGCOMMERCE_STORE_ID={ store_hash from Step 3 }
BIGCOMMERCE_CHANNEL_ID= { channel_id from the response in Step 3 }
BIGCOMMERCE_DEVTOOLS_APP_CLIENT_SECRET={ DevTools App Client Secret from Step 2 }
BIGCOMMERCE_STORE_URL={Storefront URL from Step 6 }
  1. Run yarn to install the dependencies
  2. Run yarn build to build the source files
  3. Run yarn dev to start the project.
  4. Your VueStorefront should be up and running connected to your BigCommerce instance.