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
- Carts:
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.
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:
{
"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.
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.
{
"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.
{
"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({
"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.
<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.