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 API credentials with the following permissions.
- Carts: Modify
- Channel Settings: Modify
- Sites & Routes: Modify
- Products: Read Only

For more information, see OAuth Scopes.

The BigCommerce JS Checkout SDK (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 POST request to the /channels endpoint.

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/channels

Create a Channel POST request

{
    "type": "storefront",
    "platform": "custom",
    "name": "https://{your-site}.com"
}

The response will contain an id which we will use as the channel_id in future requests.

Create Channel response

 
{
    "data": {
        "id": 20266,
        "name": "https://www.{your-site}.com",
        "platform": "custom",
        "type": "storefront",
        "date_created": "2019-09-18T22:28:36Z",
        "date_modified": "2019-09-18T22:28:36Z",
        "external_id": "",
        "is_enabled": true
    },
    "meta": {}
}

Channels created via API are visible in the BigCommerce store's Control Panel in Products > Listed On. The Orders section will now also include a filter for your channel.

Creating a site

Next, create a site for the channel by sending a POST request to the /channels/id/site endpoint.

POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/channels/{{channel_id}}/site

Create Site POST

{
    "channel_id": 20266,
    "url": "https://www.{your-site}.com"
}

This returns id which you will use as the site_id in future requests. The url value is the base path for all other routes you define for the site.

Create Site response

{
    {
    "data": {
        "id": 6,
        "url": "https://www.{your-site}.com",
        "channel_id": 20266,
        "created_at": "2019-09-19T17:08:44Z",
        "updated_at": "2019-09-19T17:08:44Z"
    },
    "meta": {}
    }
}

Creating a cart

To proceed to checkout, we'll 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 (opens in a new tab) 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.

You will first need to use JSON Web Token Standard to create a new token. Use a JWT library (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,
  "redirect_to": "https://store-id30h7ohwf.mybigcommerce.com/cart.php?action=loadInCheckout&id=bc218c65-7a32-4ab7-8082-68730c074d02&token=aa958e2b7922035bf3339215d95d145ebd9193deb36ae847caa780aa2e003e4b",
  "request_ip": "111.222.333.444"
}

The request_ip field is optional.

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 (opens in a new tab) and its possible corresponding rendering options (opens in a new tab).

FAQ

How can I work with Embedded Checkout locally?

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

Run your app on localhost.
Create a ngrok (opens in a new tab) tunnel for the localhost port to your app.
Set your Channel Site URL to the HTTPS URL of the ngrok tunnel.
View your app from the ngrok URL.

NOTE: Use https://127.0.0.1 (opens in a new tab) as the Channel site URL if you do not want to use ngrok.

Are hosted payment gateways supported with Embedded Checkout?

At this time, you cannot embed a checkout using a hosted payment gateway. See Available Payment Gateways (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 (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.

Related resources

Endpoints

Channels API reference

Overview Overview