Embedded Checkout

Embedded Checkout lets you place BigCommerce’s Optimized One-Page checkout onto an external site. This tutorial will walk you through the sequence of API calls your application should make to create a working Embedded Checkout.

This article assumes you have familiarity with the following concepts:

Creating and managing a server-side application
Making and receiving API calls from within your app
Using your application to make changes to a front end

Prerequisites

Store-level or app-level API credentials with the following scopes:

Resource	Permission level
Carts	`modify`
Channel Settings	`modify`
Sites & Routes	`modify`
Products	`read-only`

For more information, see the Guide to API Accounts.

The BigCommerce Checkout JS SDK (GitHub) (opens in a new tab) must be accessible in the browser.

Creating a channel

To allow an external website to serve the BigCommerce checkout, create a new channel by sending a request to the Create a channel endpoint. A successful response contains an id that you can use as the channel_id in future requests.

Request: Create a channel

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/channels
X-Auth-Token: {{access_token}}
Accept: application/json
Content-Type: application/json
{
  "type": "storefront",
  "platform": "custom",
  "name": "My Custom Store"
}

Channels created by API are visible in the store control panel's channel manager (opens in a new tab). You can also use the advanced search feature on the products view page (opens in a new tab), sort customers by channel (opens in a new tab), and create custom views of orders (opens in a new tab) to group or filter those entities by channel.

Creating a site

Next, create a site for the channel by sending a request to the Create a channel site endpoint. This returns an id that you can use as the site_id in future requests. The url value is the base path for all other routes you define for the site.

Request: Create a site

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/channels/{{channel_id}}/site
X-Auth-Token: {{access_token}}
Accept: application/json
Content-Type: application/json
{
  "channel_id": 20266,
  "url": "https://store.example.com"
}

Creating a cart

To proceed to checkout, you need an active cart. To create one, send a request to the REST Management API's Create a cart endpoint.

Example request: Create a cart

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts
X-Auth-Token: {{access_token}}
Accept: application/json
Content-Type: application/json
 
{
  "channel_id": 20266,
  "line_items": [
    {
      "quantity": 1,
      "product_id": 80,
      "variant_id": 64
    }
  ]
}

If you are creating a cart for a specific customer, pass in the customer_id in the request.

{
  "customer_id": 42,
  "line_items": [
    {
      "quantity": 5,
      "product_id": 191
    }
  ]
}

The response contains a cart ID you can use in subsequent requests:

Example response: Create a cart

  {
    "data": {
      "id": "33608b81-ba34-4ff2-8bab-2771aeab3f73",
    ...
    }
  }

To generate a cart redirect URL, send a request to the Create cart redirect URL endpoint. Use the cart ID returned with the Create a cart response as the cartId path parameter value.

Example response: Create cart redirect URLs

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts/{{cartId}}/redirect_urls
X-Auth-Token: {{access_token}}
Accept: application/json
Content-Type: application/json
 
{
  "cart_url": "https://store-id30h7ohwf.mybigcommerce.com/cart.php?action=load&id=bc218c65-7a32-4ab7-8082-68730c074d02&token=aa958e2b7922035bf3339215d95d145ebd9193deb36ae847caa780aa2e003e4b",
  "checkout_url": "https://store-id30h7ohwf.mybigcommerce.com/cart.php?action=loadInCheckout&id=bc218c65-7a32-4ab7-8082-68730c074d02&token=aa958e2b7922035bf3339215d95d145ebd9193deb36ae847caa780aa2e003e4b",
  "embedded_checkout_url": "https://store-id30h7ohwf.mybigcommerce.com/cart.php?embedded=1&action=loadInCheckout&id=bc218c65-7a32-4ab7-8082-68730c074d02&token=aa958e2b7922035bf3339215d95d145ebd9193deb36ae847caa780aa2e003e4b"
}

Redirecting a signed-in customer to embedded checkout

For some use cases, you may want your customer to sign in before they can begin the checkout process.

Customers can sign in using the Customer Login API. Guest shoppers do not need to be signed in. Skip to Embedding the checkout for more information on the guest shopper flow.

To redirect a signed-in customer, use the JSON Web Token Standard to create a Customer Login JWT. Use a JWT library (jwt.io) (opens in a new tab) to accomplish this. For more information, see Create JWT Using the Debugger Tool.

Next, include the embedded_checkout_url as part of the request payload you send to BigCommerce.

Example Customer Login JWT payload

{
  "iss": {{client_id}},
  "iat": 1535393113,
  "jti": {{uuid}},
  "operation": "customer_login",
  "store_hash": {{store_hash}},
  "customer_id": 2,
  "channel_id": 123,
  "redirect_to": "https://store-id30h7ohwf.mybigcommerce.com/cart.php?embedded=1&action=loadInCheckout&id=bc218c65-7a32-4ab7-8082-68730c074d02&token=aa958e2b7922035bf3339215d95d145ebd9193deb36ae847caa780aa2e003e4b",
  "request_ip": "111.222.333.444"
}

Data properties in the Customer Login JWT

The following table clarifies where the data properties for the embedded checkout JWT differ from the core Customer Login JWT properties.

Property	Type	Description
`operation`	string	The value is always `customer_login`.
`customer_id`	integer	The ID of the customer who wants to check out.
`channel_id`	integer	The sales channel that the customer is signing in to. In a headless implementation, this is the storefront's channel ID. Required for embedded checkout.
`redirect_to`	string, URL	The cart redirect URL you generated in a previous step.

Embedding the checkout

Use the embedded_checkout_url that is returned from generating redirect URLs and assemble a JSON object. It will be used by the Checkout JS SDK to determine how to render the checkout.

When the shopper is signed in, use the https://{{store-url}}/login/token/{{token}} URL as the url option for embedCheckout. For unauthenticated shoppers, use the embedded_checkout_url as the url option instead.

JSON Object

{
  "containerId": "foo-bar-checkout",
  "url": "https://store-id30h7ohwf.mybigcommerce.com/cart.php?embedded=1&action=loadInCheckout&id=bc218c65-7a32-4ab7-8082-68730c074d02&token=aa958e2b7922035bf3339215d95d145ebd9193deb36ae847caa780aa2e003e4b"
}

Pass the object to the embedCheckout method of the Checkout SDK.

embedCheckout method

embedCheckout({
  "containerId": "foo-bar-checkout",
  "url": "https://store-id30h7ohwf.mybigcommerce.com/cart.php?embedded=1&action=loadInCheckout&id=bc218c65-7a32-4ab7-8082-68730c074d02&token=aa958e2b7922035bf3339215d95d145ebd9193deb36ae847caa780aa2e003e4b"
});

This will render the checkout to an HTML element with the id you chose.

HTML element

<div id="foo-bar-checkout"></div>

Read more about the JSON object (GitHub) (opens in a new tab) and its possible corresponding rendering options (GitHub) (opens in a new tab).

FAQ

How can I work with Embedded Checkout locally?

You can use ngrok to test Embedded Checkout locally. Steps:

Start the development server using your local copy of the storefront.
Create an ngrok tunnel (ngrok.com) (opens in a new tab) to serve your localhost over a fully-qualified SSL connection.
Set your Channel Site URL to the HTTPS URL of the ngrok tunnel.
View your checkout using the ngrok URL.

Note: If you don't want to use ngrok, use https://127.0.0.1 (opens in a new tab) as the Channel site URL.

Are hosted payment gateways supported with Embedded Checkout?

At this time, you cannot embed a checkout that uses a hosted payment gateway. See Available Payment Gateways (Help Center) (opens in a new tab) to determine which type of gateway you're using.

How do I resolve Embedded Checkout 403 "Cannot start checkout session with an empty cart" Errors?

For Embedded Checkout to work correctly for shoppers using a browser with restricted privacy settings,like Apple's Safari, your checkout page must be served from the same domain as your BigCommerce storefront. For example, if your headless storefront is www.mystore.com, then your BigCommerce store's domain should be checkout.mystore.com. For more information on making Embedded Checkout on a headless WordPress storefront compatible with Safari, see BigCommerce for WordPress (Help Center) (opens in a new tab).

How do I make sure that authenticated shoppers who sign out from the checkout page are also signed out of the headless storefront?

To ensure you sign shoppers out of the checkout page and the headless storefront, pass the onSignOut option to embedCheckout to handle sign out events from the checkout page.