{"id":22542201,"url":"https://github.com/commercelayer/mfe-checkout","last_synced_at":"2026-01-27T20:22:04.206Z","repository":{"id":37081682,"uuid":"319919156","full_name":"commercelayer/mfe-checkout","owner":"commercelayer","description":"Commerce Layer Hosted Checkout","archived":false,"fork":false,"pushed_at":"2023-12-13T12:54:52.000Z","size":11265,"stargazers_count":34,"open_issues_count":11,"forks_count":38,"subscribers_count":6,"default_branch":"main","last_synced_at":"2023-12-14T10:35:34.485Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://commercelayer.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/commercelayer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-12-09T10:22:16.000Z","updated_at":"2024-03-05T13:20:13.007Z","dependencies_parsed_at":"2023-07-26T02:04:34.542Z","dependency_job_id":"4b751c17-425e-4081-b991-28e882059473","html_url":"https://github.com/commercelayer/mfe-checkout","commit_stats":null,"previous_names":["commercelayer/mfe-checkout","commercelayer/commercelayer-react-checkout"],"tags_count":91,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercelayer%2Fmfe-checkout","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercelayer%2Fmfe-checkout/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercelayer%2Fmfe-checkout/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercelayer%2Fmfe-checkout/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/commercelayer","download_url":"https://codeload.github.com/commercelayer/mfe-checkout/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248125109,"owners_count":21051759,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-07T13:09:03.979Z","updated_at":"2025-10-05T23:40:27.292Z","avatar_url":"https://github.com/commercelayer.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Commerce Layer React Checkout\n\nThe Commerce Layer Checkout application (React) provides you with a [PCI-compliant](https://commercelayer.io/security), 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.\n\n![Commerce Layer React Checkout demo](./public/demo.gif)\n\n## What is Commerce Layer?\n\n[Commerce Layer](https://commercelayer.io) 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.\n\n## Table of contents\n\n- [Getting started](#getting-started)\n- [Hosted version](#hosted-version)\n- [Features](#features)\n- [Contributors guide](#contributors-guide)\n- [Help and support](#need-help)\n- [License](#license)\n\n---\n\n## Getting started\n\n1. Create your organization and get your credentials by following one of our [onboarding tutorials](https://docs.commercelayer.io/developers/welcome).\n\n2. Set the environment variable `NEXT_PUBLIC_SLUG` on your hosting provider to your organization slug (subdomain) and be sure to build the forked repository using the node environment (`NODE_ENV`) as production.\n\n3. Deploy the forked repository to your preferred hosting service. You can deploy with one click below:\n\n[\u003cimg src=\"https://www.netlify.com/img/deploy/button.svg\" alt=\"Deploy to Netlify\" height=\"35\"\u003e](https://app.netlify.com/start/deploy?repository=https://github.com/commercelayer/mfe-checkout#NEXT_PUBLIC_SLUG) [\u003cimg src=\"https://vercel.com/button\" alt=\"Deploy to Vercel\" height=\"35\"\u003e](https://vercel.com/new/clone?repository-url=https://github.com/commercelayer/mfe-checkout\u0026build-command=pnpm%20build\u0026output-directory=out/dist\u0026env=NEXT_PUBLIC_SLUG\u0026envDescription=your%20organization%20slug)\n\n4. Build your sales channel with your favorite technologies and frameworks by leveraging our [developer resources](https://commercelayer.io/developers) and [documentation](https://docs.commercelayer.io/api).\n\n5. Get an [access token](https://docs.commercelayer.io/api/authentication) for your application. You should generate this in your sales channel or use our JavaScript [authentication library](https://github.com/commercelayer/commercelayer-js-auth).\n\n6. Create an [order](https://docs.commercelayer.io/developers/v/api-reference/orders) associated with some [line items](https://docs.commercelayer.io/developers/v/api-reference/line_items).\n\n7. Checkout the previously created order using the URL format: `\u003cyour-deployed-checkout-url\u003e/:order_id?accessToken=\u003cyour-access-token\u003e`\n\n### Example\n\n`https://checkout.yourbrand.com/PrnYhoVeza?accessToken=eyJhbGciOiJIUzUxMiJ9`\n\n## Hosted version\n\nAny 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.\n\nYou can use the hosted version of the Checkout application with the following URL format: `https://\u003cyour-organization-subdomain\u003e.commercelayer.app/checkout/:order_id?accessToken=\u003cyour-access-token\u003e`\n\n### Example\n\n`https://yourbrand.commercelayer.app/checkout/PrnYhoVeza?accessToken=eyJhbGciOiJIUzUxMiJ9`\n\n### CLI plugin\n\nIf you are using [Commerce Layer CLI](https://github.com/commercelayer/commercelayer-cli), you can leverage the [checkout plugin](https://github.com/commercelayer/commercelayer-cli-plugin-checkout/blob/main/README.md) 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):\n\n```\ncommercelayer checkout -S \u003cskuCode\u003e:\u003cquantity\u003e --open\ncommercelayer checkout -B \u003cbundleCode\u003e:\u003cquantity\u003e --open\ncommercelayer checkout -O \u003corderID\u003e --open\n```\n\n## Features\n\nThe 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.\n\nThe Checkout application includes an [order summary](#order-summary) and a checkout flow made of 3 steps:\n\n1. [Customer](#customer-step)\n2. [Delivery](#delivery-step)\n3. [Payment](#payment-step)\n\nEach step can be edited by the customer at any time. The order status determines the current step, which stays consistent across sessions.\n\nOnce the checkout is successfully completed, the customer is redirected to a [thank you page](#thank-you-page).\n\n### Order summary\n\nThe 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.).\n\n\u003e We suggest properly setting up all the [SKU](https://docs.commercelayer.io/developers/v/api-reference/skus) information (in terms of names and images) on the Commerce Layer admin dashboard or via API so that this part is fully populated.\n\n#### SKU options\n\nThe Checkout application supports [SKU options](https://docs.commercelayer.io/developers/v/api-reference/sku_options). If a line item is associated with one or more [line item options](https://docs.commercelayer.io/developers/v/api-reference/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.\n\n#### Gift cards and coupons\n\nThe Checkout application supports [gift cards](https://docs.commercelayer.io/developers/v/api-reference/gift_cards) and [coupon](https://docs.commercelayer.io/developers/v/api-reference/coupons) 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.\n\n#### Bundles\n\nThe Checkout application supports [bundles](https://docs.commercelayer.io/developers/v/api-reference/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.\n\n#### Return to cart\n\nIf the order has the attribute `cart_url` set, a \"Return to cart\" link will be displayed.\n\n### Order refresh\n\nWhen 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:\n\n```mermaid\nflowchart LR\n    A[Start] --\u003e B{order.autorefresh?}\n    B -- true --\u003e C{Token type?}\n    C -- Sales channel --\u003e G\n    C -- Customer token --\u003e D{order.guest?}\n    D -- false --\u003e G[No refresh]\n    D -- true --\u003e F\n    B -- false ----\u003e F[Refresh sync]\n```\n\n### Customer step\n\nHere is where customers provide their email address, billing and shipping information.\n\n#### Optional billing info\n\nIt is possible to display an optional billing info, if not required by the market configuration, by setting the organization's `config` attribute, as follows:\n\n```json\n{\n  \"mfe\": {\n    \"default\": {\n      \"checkout\": {\n        \"optional_billing_info\": true\n      }\n    }\n  }\n}\n```\n\n#### Logged customers\n\nIf the access token used to build the checkout URL is a [customer token](https://docs.commercelayer.io/developers/authentication/password) 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.\n\n#### Digital products\n\nIn the case of digital product purchases (i.e. SKUs with the `do_not_ship` flag enabled), the shipping address form doesn't appear.\n\n#### Locking the shipping country code\n\nIf 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.\n\n#### Custom list of countries and states\n\nYou 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:\n\n```json\n{\n  \"mfe\": {\n    \"default\": {\n      \"checkout\": {\n        \"default_country\": \"IT\",\n        \"billing_countries\": [\n          {\n            \"value\": \"ES\",\n            \"label\": \"Espana\"\n          },\n          {\n            \"value\": \"IT\",\n            \"label\": \"Italia\"\n          },\n          {\n            \"value\": \"US\",\n            \"label\": \"Unites States of America\"\n          }\n        ],\n        \"billing_states\": {\n          \"US\": [\n            {\n              \"value\": \"CA\",\n              \"label\": \"California\"\n            },\n            {\n              \"value\": \"TX\",\n              \"label\": \"Texas\"\n            }\n          ],\n          \"IT\": [\n            {\n              \"value\": \"FI\",\n              \"label\": \"Firenze\"\n            },\n            {\n              \"value\": \"PO\",\n              \"label\": \"Prato\"\n            },\n            {\n              \"value\": \"LI\",\n              \"label\": \"Livorno\"\n            }\n          ]\n        }\n      }\n    }\n  }\n}\n```\n\nIn 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.\n\nYou 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](https://docs.commercelayer.io/provisioning/api-reference/organizations#micro-frontends-configuration).\n\n\n### Delivery step\n\nHere is where customers select a shipping method for each shipment of their order. [External shipping cost](https://docs.commercelayer.io/core/external-resources/external-shipping-costs) are partially supported by the Checkout application at the moment.\n\n#### Single shipping method\n\nIf there is only one available [shipping method](https://docs.commercelayer.io/developers/v/api-reference/shipping_methods) per shipment, the Checkout application will autoselect that shipping method for each shipment of the order and skip the _Delivery_ step.\n\n#### Shipping zone check\n\nIf the shipping address is outside the associated [shipping zone](https://docs.commercelayer.io/developers/v/api-reference/shipping_zones) customers will receive an error and won't be able to place the order.\n\n#### Out-of-stock items\n\nIf 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.\n\n#### Digital products\n\nIn the case of digital product purchases (i.e. SKUs with the `do_not_ship` flag enabled), this step doesn't appear.\n\n### Payment step\n\nHere is where customers select a payment method and place the order.\n\n\u003e We're working to make all the [payment gateways](https://docs.commercelayer.io/developers/v/how-tos/payments) supported by Commerce Layer available out-of-the-box in the Checkout application. [External payments](https://docs.commercelayer.io/developers/v/how-tos/payments/external-payments) are not supported by the Checkout application at the moment. For all the other gateways information please refer to the table below.\n\n| Payment gateway                                                                                 | Supported payment methods                                                                                                                               | Customer wallet |\n| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |\n| [Adyen](https://docs.commercelayer.io/developers/v/how-tos/payments/adyen)                      | Credit card / [PayPal](https://docs.adyen.com/payment-methods/paypal/web-drop-in) / [Klarna](https://docs.adyen.com/payment-methods/klarna/web-drop-in) | \u0026check;         |\n| [Braintree](https://docs.commercelayer.io/developers/v/how-tos/payments/braintree)              | Credit card                                                                                                                                             | \u0026check;         |\n| [Checkout.com](https://docs.commercelayer.io/core/how-tos/placing-orders/payments/checkout.com) | Credit card                                                                                                                                             | \u0026check;         |\n| [Klarna](https://docs.commercelayer.io/developers/v/how-tos/payments/klarna)                    | Klarna                                                                                                                                                  | \u0026cross;         |\n| [PayPal](https://docs.commercelayer.io/developers/v/how-tos/payments/paypal)                    | PayPal                                                                                                                                                  | \u0026cross;         |\n| [Stripe](https://docs.commercelayer.io/developers/v/how-tos/payments/stripe)                    | Credit card / Apple Pay / Google Pay / PayPal / Klarna / Link / Affirm                                                                                                  | \u0026check;         |\n| [Manual gateway](https://docs.commercelayer.io/developers/v/how-tos/payments/manual-payments)   | Manual payment                                                                                                                                          | \u0026cross;         |\n\n\u003e To automatically accept payment methods enabled in the Stripe dashboard please make sure to properly set up the `auto_payments` option on your [Stripe gateway](https://docs.commercelayer.io/core/v/api-reference/stripe_gateways).\n\n\u003e When using PayPal via Adyen please make sure to properly [set up third-party access](https://docs.adyen.com/payment-methods/paypal/web-drop-in#grant-api-access) on your PayPal first.\n\n\u003e Adyen Payments API supported by the Checkout application are from `v68` to `v71`. Make sure that your Adyen payment gateway is configured properly on Commerce Layer.\n\n#### Logged customers\n\nIf the access token used to build the checkout URL is a [customer token](https://docs.commercelayer.io/developers/authentication/password) customers will see their saved credit cards in their customer wallet and will be able to reuse them to accelerate the payment process. The customer will also be able to view the thank you page after an order is approved.\n\n#### Single payment method\n\nIf there is only one [payment method](https://docs.commercelayer.io/developers/v/api-reference/payment_methods) 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.\n\n#### Zero-balance\n\nIn 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.\n\n#### Privacy acceptance\n\nIf 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.\n\n### Order subscription\n\n#### Recurring items\n\nWhen a line item includes a frequency, placing the order [creates an order subscription](https://docs.commercelayer.io/core/v/how-tos/placing-orders/subscriptions/generating-the-subscriptions). 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.\n\n#### Target order \n\nIf 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.\n\n### Thank you page\n\nThe 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.\n\n#### Custom thank you page URL\n\nIt 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:\n\n```json\n{\n  \"mfe\": {\n    \"default\": {\n      \"checkout\": {\n        \"thankyou_page\": \"https://example.com/thanks/:lang/:order_id\"\n      }\n    }\n  }\n}\n```\n\nYou 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](https://docs.commercelayer.io/provisioning/api-reference/organizations#micro-frontends-configuration).\n\n### Timed Checkout\n\nThe Commerce Layer Checkout supports timed sessions for orders, allowing you to set an expiration for the checkout process. This feature is useful for scenarios where you want to reserve items for a limited time or enforce a strict purchase window.\n\n#### How it works\n\nThe timed checkout feature is enabled by filling the `expires_at` attribute of the order resource. The behaviour can be customized by using the optional `expiration_info` attribute (JSON object):\n\n- `expires_at`: a timestamp (ISO 8601 format) indicating when the checkout session expires.\n- `expiration_info`: a JSON object containing:\n  - `active_message`: a message shown in the order summary to inform the user about the expiry.\n  - `expired_message`: a message displayed on the expired checkout page.\n  - `return_url`: a URL to redirect the user from the expired page (e.g., back to the cart or a custom page).\n\nIf the `expiration_info` is partially or not populated, default messages will be displayed. If the `return_url` is missing, the checkout will use the order's `return_url` if present.\n\n#### Options and UI behavior\n\n- While the checkout is active, a countdown timer is shown in the summary, using the `active_message` from `expiration_info`.\n- If the timer expires, the checkout page will display the `expired_message` and optionally provide a button or link to the `return_url`.\n- The timer and messages are fully customizable via the `expiration_info` JSON.\n\n#### Example order attributes\n\n```json\n{\n  \"expires_at\": \"2025-08-19T15:30:00Z\",\n  \"expiration_info\": {\n    \"active_message\": \"You have 10 minutes to complete your purchase.\",\n    \"expired_message\": \"Your session has expired. Please start your checkout again.\",\n    \"return_url\": \"https://yourshop.com/cart\"\n  }\n}\n```\n\n\u003e [!TIP]\n\u003e Timed checkout is ideal for ticketing, limited inventory, or flash sale scenarios.\n\n### Supported languages\n\nThe Checkout application language is set by the `language_code` attribute of the order. At the moment, languages supported out of the box are:\n\n- English\n- Italian\n- German\n- Polish\n- Spanish\n- French\n- Hungarian\n- Portuguese\n\n\u003e The fallback language is English.\n\nIf you want to contribute and translate the Checkout application into a language that's not currently available feel free to [create a PR](#contributors-guide).\n\n### Google Tag Manager integration\n\nIf `gtm_id` attribute is set on the [organization](https://docs.commercelayer.io/developers/v/api-reference/organization/object) settings it will be used to send [Enhanced Ecommerce](https://developers.google.com/analytics/devguides/collection/ua/gtm/enhanced-ecommerce) events. The Checkout application currently tracks the following events:\n\n- `begin_checkout`\n- `add_shipping_info`\n- `add_payment_info`\n- `purchase`\n\nIf the _Delivery_ step is [automatically populated](#single-shipping-method), 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.\n\n## Contributors guide\n\n1. Fork [this repository](https://github.com/commercelayer/mfe-checkout) (you can learn how to do this [here](https://help.github.com/articles/fork-a-repo)).\n\n2. Clone the forked repository like so:\n\n```bash\ngit clone https://github.com/\u003cyour username\u003e/mfe-checkout.git \u0026\u0026 cd mfe-checkout\n```\n\n3. First, install dependencies and run the development server:\n\n```bash\npnpm install\npnpm dev\n```\n\n4. Set your environment with `.env.local` starting from `.env.local.sample`.\n\n5. Open [http://localhost:3000](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=\u003cyour-access-token\u003e`.\n\n6. Make your changes and create a pull request ([learn how to do this](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request)).\n\n7. Someone will attend to your pull request and provide some feedback.\n\n## Need help?\n\n- Join [Commerce Layer's Discord community](https://discord.gg/commercelayer).\n- Ping us on [Bluesky](https://bsky.app/profile/commercelayer.io), [X (formerly Twitter)](https://x.com/commercelayer), or [LinkedIn](https://www.linkedin.com/company/commerce-layer).\n- Is there a bug? Create an [issue](https://github.com/commercelayer/mfe-checkout/issues) on this repository.\n\n## License\n\nThis repository is published under the [MIT](LICENSE) license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommercelayer%2Fmfe-checkout","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcommercelayer%2Fmfe-checkout","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommercelayer%2Fmfe-checkout/lists"}