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

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.

You can configure Checkout routing in the Merchant Center.

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.

Alternatively, use the commercetools integration-layer checkout-rules commands in the commercetools CLI. The add command appends a rule to the list. A rule with neither --store nor --country is a catch-all, and the CLI keeps it last. The following commands create the rules from the previous table:

commercetools integration-layer checkout-rules add --store retail-de --application-key checkout-de
commercetools integration-layer checkout-rules add --country US --application-key checkout-us
commercetools integration-layer checkout-rules add --application-key checkout-default

Both --store and --country accept comma-separated lists, and a rule matches if any listed value matches. Use --position to insert a rule elsewhere in the order, but never after a catch-all.

To review and change the rules, use the following commands:

commercetools integration-layer checkout-rules get
commercetools integration-layer checkout-rules remove 2
commercetools integration-layer checkout-rules set --file checkout-rules.json

The get command lists the rules in match order, and remove takes a position from that list. The set command replaces the whole list with the rules in a JSON file, which lets you keep the rules in version control. The remove and set commands ask for confirmation. Pass --force to skip the prompt, which is required in non-interactive environments such as CI. At least one rule must remain, so remove refuses to delete the last rule.

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.