# Configuring BigCommerce

# Create an API Account

The Vue Storefront integration for BigCommerce requires API Access to communicate with your store. In BigCommerce, API Access is provided through API accounts.

  1. To create your API Account, first log in to your BigCommerce instance, go to Settings -> API accounts, and click on the + Create API Account button.

API accounts

  1. Use V2/V3 API token as Token type.
  2. Set up your API Account Name.

Create API account

  1. Copy the API path.
  2. Add the highest OAuth scopes:
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 create
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
Store logs read-only
  1. Save.
  2. 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.

API Credentials

TIP

Values of Client ID, Client secret, Access token and API path will be necessary to configure your VSF app.

# API configuration

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.

# Create a new Channel

A channel is anywhere a merchant sells their products. This encompasses headless storefronts, marketplaces, POS systems, and marketing platforms. - Channels - BigCommerce Dev Center (opens new window)

The goal of this step is to create a custom channel for our Vue Storefront app. If you're using multiple storefronts, it's necessary to create a custom channel for each storefront.

  1. Open the Create a Channel - API Reference (opens new window) page.
  2. In the Auth section, enter your Access token as the X-Auth-TokenŪ.
  3. Now, you need your store_hash, it can be found in the API path link between https://api.bigcommerce.com/stores/ and /v3/. Paste it in the Parameters section as store_hash.
  4. In Body section, use this JSON to create a custom channel:
{
  "name": "VueStorefront",
  "platform": "custom",
  "type": "storefront",
  "status": "active"
}
  1. Send API Request.
  2. You should see 200 OK status and information about created channel in the Response section.
  3. Channel id will be required to create a Create a Channel Site.

Create channel

# Create a Channel Site

Sites link headless storefronts to sales channels. - Sites - BigCommerce Dev Center (opens new window)

Each of created channels need a site with information about the domain where it will be available.

  1. Open Create a Channel Site (opens new window) page.
  2. Use your Access token in Auth section as X-Auth-Token.
  3. Use your store_hash in Parameters section.
  4. Copy the created channel id and use it as your channel_id in the Parameters section.
  5. In Body section, use this JSON with your domain information to create a custom channel:
{
  "url": "https://your-vsf-domain.com",
  "channel_id": 1193746
}

Note that the same channel_id appears in both Parameters and Body.

  1. Send API Request.
  2. You should see 200 OK status and information about created channel site in the Response section.
  3. Site id will be required to create a Create a Channel Site.

Create site

# Create site routes

Site routes tell BigCommerce how to link to pages on a headless storefront. To create a route for a site, send a POST request to /stores/STORE_HASH/v3/sites/{site_id}/routes. - Site routes - BigCommerce Dev Center (opens new window)

Vue Storefront integration with BigCommerce is using a feature called Embedded checkout (opens new window) to generate a BigCommerce checkout in your application. This checkout includes few links (like Edit cart) which navigates to BigCommerce storefront by default. We'd recommend to change that behaviour and navigate to VSF app instead. It can be done with Site routes.

  1. Open Create a Site Route (opens new window) page.
  2. In the Auth section, enter your Access token as the X-Auth-Token.
  3. Use your store_hash in Parameters section.
  4. Copy the created site id and use it as site_id in Parameters section..
  5. In Body section to create a site route for cart:
{
  "type": "cart",
  "matching": "*",
  "route": "/"
}
  1. Repeat the same steps for home:
{
  "type": "home",
  "matching": "*",
  "route": "/"
}
  1. Repeat the same steps for create_account:
{
  "type": "create_account",
  "matching": "*",
  "route": "/"
}
  1. Repeat the same steps for forgot_password:
{
  "type": "forgot_password",
  "matching": "*",
  "route": "/"
}
  1. It's ready. Now, redirects from embedded checkout will point user to Vue Storefront application instead of BigCommerce storefront.

# Add Categories to your channel

  1. Open Upsert Category Trees (opens new window) page.
  2. Click on Try it a modal should appear
  3. Use your Access token in request profile as Access Token
  4. Use your store_hash in request profile as Store Hash
  5. Copy the created channel id and use it as your channel inside the channels array for the request body

example using 12345678 as your Channel ID

[
  {
    "name": "custom channel tree", // You can put any name you want here
    "channels": [
      12345678
    ]
  }
]

Take note that 1 category tree is allowed to 1 channel only.

  1. Head over to https://<store_hash>.mybigcommerce.com/manage/products/categories (opens new window) and create your categories for your custom channel

Create categories

  1. Head over to https://<store_hash>.mybigcommerce.com/manage/products (opens new window) and assign your products to your custom channel and to categories

Add products to Channels

Add products to Categories

Add products to Categories 2

# Create a custom Cart ID field on Customers entity

Creating a Cart ID field on Customers entity enables using customer cart across different devices and sessions.

  1. In BigCommerce management panel, navigate to Settings -> Account sign up form.
  2. Select Text Field in Create a New Field... dropdown.

Form fields

  1. Use Cart ID as Field Name. No other value is required to be set.

Cart ID

  1. Save.

# Configure Content-Security-Policy Header

To render embedded checkout in your Vue Storefront application, you need to configure CSP header with information about a trusted domain where it can be used.

  1. Navigate to Settings -> Security & Privacy.
  2. Scroll to Storefront section.
  3. Select Specify my own CSP header option in Configure Content-Security-Policy Header Value field.
  4. Use frame-ancestors https://your-vsf-domain.com with your domain information.

Configure Content-Security-Policy Header

TIP

If you have more than one storefront, you can add them separated with spaces or use a wildcard. Example: frame-ancestors https://store1.your-vsf-domain.com https://store2.your-vsf-domain.com or frame-ancestors https://*.your-vsf-domain.com.

# Guest token

Guest token is required for proper working of API calls of unauthorized user. To retrieve guest token:

  1. Navigate to the Home in BigCommerce management panel.
  2. Find Review & test your store block.
  3. Copy the preview code. This is the guest token.

Preview code

  1. This token will be necessary during setup of Vue Storefront app.

# Make your store active

To avoid problems with logging in and embedding the checkout, you need to make your store active.

  1. Navigate to Channel Manager.
  2. Find the default BigCommerce storefront (the one with BigCommerce logo next to it).
  3. Press on ... button and select Make active.

Make active

  1. Verify that this storefront has the Active label.

Active channels