Configuring BigCommerce

Create an API Account

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

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

4. Copy the API path.
5. Add the highest OAuth scopes:

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

The goal of this step is to create a custom channel for our Alokai 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 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"
}

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

Create a Channel Site

Sites link headless storefronts to sales channels. - Sites - BigCommerce Dev Center

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

1. Open Create a Channel Site 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.

6. Send API Request.
7. You should see 200 OK status and information about created channel site in the Response section.
8. Site id will be required to create a Create a Channel 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

Alokai integration with BigCommerce is using a feature called Embedded checkout 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 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": "/"
}

6. Repeat the same steps for home:

{
  "type": "home",
  "matching": "*",
  "route": "/"
}

7. Repeat the same steps for create_account:

{
  "type": "create_account",
  "matching": "*",
  "route": "/"
}

8. Repeat the same steps for forgot_password:

{
  "type": "forgot_password",
  "matching": "*",
  "route": "/"
}

9. It's ready. Now, redirects from embedded checkout will point user to Alokai application instead of BigCommerce storefront.

Add Categories to your channel

1. Open Upsert Category Trees 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.

6. Head over to https://<store_hash>.mybigcommerce.com/manage/products/categories and create your categories for your custom channel

7. Head over to https://<store_hash>.mybigcommerce.com/manage/products and assign your products to your custom channel and to categories

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.

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

4. Save.

Configure Content-Security-Policy Header

To render embedded checkout in your Alokai 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.

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.

4. This token will be necessary during setup of Alokai 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.

4. Verify that this storefront has the Active label.