The Commerce Layer Checkout application (React) provides you with a PCI-compliant, PSD2-compliant, and production-ready checkout flow powered by Commerce Layer APIs. You can fork this repository and deploy it to any hosting service or use it as a reference application to build your own.
Commerce Layer is a multi-market commerce API and order management system that lets you add global shopping capabilities to any website, mobile app, chatbot, wearable, voice, or IoT device, with ease. Compose your stack with the best-of-breed tools you already mastered and love. Make any experience shoppable, anywhere, through a blazing-fast, enterprise-grade, and secure API.
-
Create your organization and get your credentials by following one of our onboarding tutorials.
-
Set the environment variable
NEXT_PUBLIC_SLUGon your hosting provider to your organization slug (subdomain) and be sure to build the forked repository using the node environment (NODE_ENV) as production. -
Deploy the forked repository to your preferred hosting service. You can deploy with one click below:
-
Build your sales channel with your favorite technologies and frameworks by leveraging our developer resources and documentation.
-
Get an access token for your application. You should generate this in your sales channel or use our JavaScript authentication library.
-
Create an order associated with some line items.
-
Checkout the previously created order using the URL format:
<your-deployed-checkout-url>/:order_id?accessToken=<your-access-token>
https://checkout.yourbrand.com/PrnYhoVeza?accessToken=eyJhbGciOiJIUzUxMiJ9
Any Commerce Layer account comes with a hosted version of the Checkout application that is automatically enabled. You can customize it by adding your organization logo, favicon, primary color, Google Tag Manager ID, support telephone, and email address.
You can use the hosted version of the Checkout application with the following URL format: https://<your-organization-subdomain>.commercelayer.app/checkout/:order_id?accessToken=<your-access-token>
https://yourbrand.commercelayer.app/checkout/PrnYhoVeza?accessToken=eyJhbGciOiJIUzUxMiJ9
If you are using Commerce Layer CLI, you can leverage the checkout plugin to generate the URL from an SKU code (using the -S flag), a bundle code (using the -B flag), or an order ID (using the -O flag):
commercelayer checkout -S <skuCode>:<quantity> --open
commercelayer checkout -B <bundleCode>:<quantity> --open
commercelayer checkout -O <orderID> --open
The Commerce Layer Checkout application supports most of the main features available through the Commerce Layer API. We're working to add a few missing ones within the next development iterations.
The Checkout application includes an order summary and a checkout flow made of 3 steps:
Each step can be edited by the customer at any time. The order status determines the current step, which stays consistent across sessions.
Once the checkout is successfully completed, the customer is redirected to a thank you page.
The Checkout application shows a visual summary of the order that's about to be placed detailing all the involved line items (frequency of recurring items, order amounts, shipping costs, taxes, discounts, etc.).
We suggest properly setting up all the SKU information (in terms of names and images) on the Commerce Layer admin dashboard or via API so that this part is fully populated.
The Checkout application supports SKU options. If a line item is associated with one or more line item options the details are visible in the order summary. Line item option prices aren't displayed but they are included in the line item amount.
The Checkout application supports gift cards and coupon codes (just fill in the related field in the order summary). You can use a gift card or coupon to pay — in total or in part — for the order. A single gift card and a coupon code can also be used together to pay for the same order.
The Checkout application supports bundles and shows them as a single item both in the order summary and within the Delivery step. The SKUs belonging to bundles may still be split across more than one shipment, based on their availability and the selected inventory model strategy.
If the order has the attribute cart_url set, a "Return to cart" link will be displayed.
When the checkout is opening, after getting the organization settings, the order might be refreshed if some conditions are met. Check the flowchart below to better understand how this logic works:
flowchart LR
A[Start] --> B{order.autorefresh?}
B -- true --> C{Token type?}
C -- Sales channel --> G
C -- Customer token --> D{order.guest?}
D -- false --> G[No refresh]
D -- true --> F
B -- false ----> F[Refresh sync]
Here is where customers provide their email address, billing and shipping information.
If the access token used to build the checkout URL is a customer token customers can select one of their saved addresses from their address book and use it as the billing and/or shipping address. If the customer has only one address in the address book the Checkout application will use this address as the billing and shipping address and skip the Customer step.
In the case of digital product purchases (i.e. SKUs with the do_not_ship flag enabled), the shipping address form doesn't appear.
If the order has the attribute shipping_country_code_lock set, customers can select only the specified country code in the shipping address form. If they select a different country for the billing address, the shipping address section will open automatically with the country code already selected and disabled.
You can configure a custom list of countries and/or states for billing and shipping address forms, along with specifying a default country preselected at the organization level of the Provisioning API. This can be achieved by setting the config attribute as follows:
{
"mfe": {
"default": {
"checkout": {
"default_country": "IT",
"billing_countries": [
{
"value": "ES",
"label": "Espana"
},
{
"value": "IT",
"label": "Italia"
},
{
"value": "US",
"label": "Unites States of America"
}
],
"billing_states": {
"US": [
{
"value": "CA",
"label": "California"
},
{
"value": "TX",
"label": "Texas"
}
],
"IT": [
{
"value": "FI",
"label": "Firenze"
},
{
"value": "PO",
"label": "Prato"
},
{
"value": "LI",
"label": "Livorno"
}
]
}
}
}
}
}In the example above, the billing form will have just three countries, custom provinces/states for Italy and USA, and the default country preselected (set to Italy) for both billing and shipping forms.
You can use default_country, billing_countries, billing_states, shipping_countries and shipping_states as keys. The option can also be customized per market in scope. You can read more about the organization config here.
Here is where customers select a shipping method for each shipment of their order. External shipping cost are partially supported by the Checkout application at the moment.
If there is only one available shipping method per shipment, the Checkout application will autoselect that shipping method for each shipment of the order and skip the Delivery step.
If the shipping address is outside the associated shipping zone customers will receive an error and won't be able to place the order.
If one of the items in the order is out of stock customers will get an error message and won't be able to place the order. If the order has the attribute cart_url set, the error message will contain a link to let them go back and edit the shopping cart.
In the case of digital product purchases (i.e. SKUs with the do_not_ship flag enabled), this step doesn't appear.
Here is where customers select a payment method and place the order.
We're working to make all the payment gateways supported by Commerce Layer available out-of-the-box in the Checkout application. External payments are not supported by the Checkout application at the moment. For all the other gateways information please refer to the table below.
| Payment gateway | Supported payment methods | Customer wallet |
|---|---|---|
| Adyen | Credit card / PayPal / Klarna | ✓ |
| Braintree | Credit card | ✓ |
| Klarna | Klarna | ✗ |
| PayPal | PayPal | ✗ |
| Stripe | Credit card / Apple Pay / Google Pay / PayPal / Klarna | ✓ |
| Manual gateway | Manual payment | ✗ |
To automatically accept payment methods enabled in the Stripe dashboard please make sure to properly set up the
auto_paymentsoption on your Stripe gateway.
When using PayPal via Adyen please make sure to properly set up third-party access on your PayPal first.
Adyen Payments API supported by the Checkout application are from
v68tov71. Make sure that your Adyen payment gateway is configured properly on Commerce Layer.
If the access token used to build the checkout URL is a customer token customers will see their saved credit cards in their customer wallet and will be able to reuse them to accelerate the payment process.
If there is only one payment method available in the market the order belongs to, the Checkout application will autoselect that payment method and let you directly add your payment details to the order.
In case the order balance is zero — e.g. the customer is paying with a gift card or coupon code for the full amount of the order — this step doesn't appear.
If the privacy_url and terms_url attributes of the order are set an info paragraph will be displayed before the "Place order" button, including the related links and a checkbox to accept the terms. Customers won't be able to place the order unless they check it and agree.
When a line item includes a frequency, placing the order creates an order subscription. To activate the subscription, the payment source must be saved in the customer's wallet. Therefore, during checkout with a customer token, the payment source is automatically saved. However, if a guest is checking out, they will receive an alert indicating that the subscription will not renew successfully without a saved payment source.
If a customer's payment source has expired or been deleted, or if the order initiating the subscription was placed as a guest, the resulting target order will be pending. Upon placement, the payment source will be automatically saved in the customer's wallet, and the order subscription will be automatically updated with the new payment source.
The page is displayed on successful order placement and features a recap of the order in terms of SKUs, bundles, billing/shipping addresses, and payment information. It is possible to show some support references (phone and email) by setting the support_phone and support_email attributes of the order. If the order's return_url attribute is set a link to continue shopping will be displayed on the page as well.
It is possible to provide a custom thank you page URL at the organization level of the Provisioning API by setting the config attribute, as follows:
{
"mfe": {
"default": {
"checkout": {
"thankyou_page": "https://example.com/thanks/:lang/:order_id"
}
}
}
}You can use :lang, :order_id and :access_token as parameters that will be replaced with the values used by the Checkout. The option can also be customized per market in scope. You can read more about the organization config here.
The Checkout application language is set by the language_code attribute of the order. At the moment, languages supported out of the box are:
- English
- Italian
- German
- Polish
- Spanish
- French
- Hungarian
- Portuguese
The fallback language is English.
If you want to contribute and translate the Checkout application into a language that's not currently available feel free to create a PR.
If gtm_id attribute is set on the organization settings it will be used to send Enhanced Ecommerce events. The Checkout application currently tracks the following events:
begin_checkoutadd_shipping_infoadd_payment_infopurchase
If the Delivery step is automatically populated, the add_shipping_info event will be fired as soon as the Checkout application sets the related shipping method. If the customer opens the Delivery step from the UI and clicks on the "Continue to payment" button, the event will be fired once more.
-
Fork this repository (you can learn how to do this here).
-
Clone the forked repository like so:
git clone https://github.com/<your username>/mfe-checkout.git && cd mfe-checkout- First, install dependencies and run the development server:
pnpm install
pnpm dev-
Set your environment with
.env.localstarting from.env.local.sample. -
Open http://localhost:3000 with your browser to see the result. You can use the following format to open the checkout:
http://localhost:3000/:orderId?accessToken=<your-access-token>. -
Make your changes and create a pull request (learn how to do this).
-
Someone will attend to your pull request and provide some feedback.
- Join Commerce Layer's Discord community.
- Ping us on Bluesky, X (formerly Twitter), or LinkedIn.
- Is there a bug? Create an issue on this repository.
This repository is published under the MIT license.