Checkout integration

Route shoppers from the Commerce Integration Layer to a commercetools Checkout Application in either Checkout mode.

Checkout integration workflow

The Commerce Integration Layer acts as the backend-for-frontend (BFF) for Checkout. Your storefront starts the checkout flow through the Experience API, which creates a Checkout Session for your Project. Your storefront passes that Checkout Session to the Checkout Browser SDK, which renders the Checkout UI and creates the Order. Checkout creates the Order and processes the payment, not the Commerce Integration Layer.

The integration uses the same Checkout SDK contract as any other Checkout integration, so Connectors, Payment Integrations, and customization behave as described in the Checkout documentation. The Commerce Integration Layer only adds routing: for each shopper, it decides which Checkout Application and mode to use.

Both Checkout modes are supported:

Complete Checkout mode: Checkout renders addresses, shipping method, payment, and order confirmation.
Payment Only mode: Checkout renders the payment step only. You keep your own flow for the rest.

B2B Orders

For B2B checkout, place the Order with the placeOrder mutation instead of starting a Checkout flow. placeOrder places the Order as the Associate in the selected Business Unit, so the permissions of the Associate and the Approval Rules of the Business Unit apply to the Order. It doesn't collect a payment. To collect one, use an extension.

Provision Checkout

Provision Checkout as you would for any other integration: install at least one Connector, then create a Checkout Application for each checkout experience. See the Getting started workflow in the Checkout documentation.

Configure Checkout routing

Configure Checkout routing in the Commerce Integration Layer application in the Merchant Center. Routing is an ordered list of rules. Each rule matches a Store, a country, or both, and names the Checkout Application to use. An empty cell matches any value. The Commerce Integration Layer evaluates the rules in order and selects the first matching rule.

Store	Country	Checkout Application
`retail-de`		`checkout-de`
	`US`	`checkout-us`
		`checkout-default`

With these rules, shoppers in the retail-de Store go to checkout-de regardless of country. Shoppers outside the retail-de Store who browse from the US go to checkout-us. All other shoppers go to checkout-default.

Rules match against the country and Store on the shopper's session.

If no rule matches, starting a Checkout flow fails. Add a catch-all rule so every shopper can reach Checkout.

Start a Checkout flow

Call the beginPayment mutation to start a flow for the shopper's active Cart. It resolves the Checkout routing for the current session and creates a Checkout Session.

These diagrams show where beginPayment fits into the Checkout integration flows, with the Commerce Integration Layer as the BFF.

Complete Checkout flow:

Payment Only flow:

beginPayment returns the following fields:

Field	Description
`paymentTicket`	The Checkout Session ID. Pass it as the `sessionId` argument to `checkoutFlow` or `paymentFlow` in the Checkout Browser SDK.
`projectKey`	Your Project key. Pass it to the Browser SDK.
`region`	The Region in which the Checkout Application is hosted. Pass it to the Browser SDK.
`mode`	`COMPLETE` or `PAYMENT_ONLY`. Determines whether to call `checkoutFlow` or `paymentFlow`.

To know which method to prepare for before starting the flow, query { viewer { checkoutMode } }.

The Checkout Session isn't the shopper session that authorizes requests to the Commerce Integration Layer. Keep the session token and the paymentTicket separate: the session token authorizes the Commerce Integration Layer, and the paymentTicket authorizes Checkout.

Payment actions after checkout

beginPayment starts a checkout or payment flow. Later actions on an authorized Payment, such as a refund, capture, cancellation, or reversal, aren't modeled in the Commerce Integration Layer schema. Use the Checkout Payment Intents API from a schema extension.