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:
Store-level or app-level API credentials with the following scopes:
For more information, see the Guide to API Accounts.
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.
Channels created by API are visible in the store control panel’s channel manager. You can also use the advanced search feature on the products view page, sort customers by channel, and create custom views of orders to group or filter those entities by channel.
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.
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.
If you are creating a cart for a specific customer, pass in the customer_id in the request.
The response contains a cart ID you can use in subsequent requests:
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.
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) 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.
The following table clarifies where the data properties for the embedded checkout JWT differ from the core Customer Login JWT properties.
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.
Pass the object to the embedCheckout method of the Checkout SDK.
This will render the checkout to an HTML element with the id you chose.
Read more about the JSON object (GitHub) and its possible corresponding rendering options (GitHub).
You can use ngrok to test Embedded Checkout locally. Steps:
Note: If you don’t want to use ngrok, use https://127.0.0.1 as the Channel site URL.
At this time, you cannot embed a checkout that uses a hosted payment gateway. See Available Payment Gateways (Help Center) to determine which type of gateway you’re using.
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).
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.