Checkout Events and Messages

Messages and events let you respond instantly to Payment or Session issues in the UI while ensuring your backend automates confirmations, ERP syncs, and Order reconciliations.

Messages and events overview

Implement Checkout Messages

Use Checkout Messages primarily to update the frontend UI or trigger local application logic. These messages help detect problems early, provide useful feedback to Customers, and support debugging or Customer service workflows.

Unlike Composable Commerce Messages, Checkout Messages aren't stored in the Composable Commerce platform. The platform scopes them to the Customer's active checkout Session and delivers them in-browser through event listeners.

Here's the schema of a sample Checkout Message:

{
  "severity": "info",
  "code": "order_created",
  "message": "Order {orderId} created.",
  "payload": {
    "order": {
      "id": "{orderId}"
    }
  },
  "correlationId": "spa/commercetools-checkout/1729263187262/565301612087128"
}

The SDK provides the following handler callbacks:

• onInfo: informational events (for example checkout_started, checkout_completed).
• onWarn: non-critical warnings (for example payment_integration_not_available, deprecated_fields).
• onError: recoverable and fatal issues (for exampleexpired_session, non_orderable_cart_error, payment_failed).

The following sample code blocks show how to wire your Checkout Message handlers in JavaScript and the Checkout Browser SDK:

<script>
  ctc('paymentFlow', { // Or `checkoutFlow`
    projectKey: '{projectKey}',
    region: '{region}',
    sessionId: '{sessionId}',
    locale: 'en',
    onInfo: function (evt) {
      console.log('[info]', evt.code, evt.payload);
    },
    onWarn: function (evt) {
      console.warn('[warn]', evt.code, evt.payload);
    },
    onError: async function (evt) {
      console.error('[error]', evt.code, evt.payload);
    },
    logInfo: true,
    logWarn: true,
    logError: true,
  });
</script>

import { checkoutFlow } from '@commercetools/checkout-browser-sdk';

checkoutFlow({ // or paymentFlow
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  locale: '{locale}',
  onInfo: (evt) => console.log('[info]', evt.code, evt.payload),
  onWarn: (evt) => console.warn('[warn]', evt.code, evt.payload),
  onError: (evt) => console.error('[error]', evt.code, evt.payload),
  logInfo: true,
  logWarn: true,
  logError: true,
  // Other configuration properties.
});

The following list shows the recommended Checkout Messages to handle, sorted by priority:

1. Handle session lifecycle: expired_session, failed_to_refresh_session
2. Validate cart readiness: non_orderable_cart_error, no_shipping_methods
3. Monitor payments: payment_failed, connector_error
4. Handle gift cards: gift_card_redeem_error, gift_card_balance_error

Here are a few key UI actions:

• Redirect on Order creation (checkout_completed)
• Prompt Customers to correct shipping or address issues
• Retry or offer alternative Payment methods

Subscribe to Checkout Events

import { SubscriptionDraft } from '@commercetools/platform-sdk';

async function createSQSCheckoutSubscription(
  storeKey: string,
  sqsQueueUrl: string,
  sqsRegion: string,
  code: string
) {
  const draft: SubscriptionDraft = {
	key: 'orders-payments-subscription',
	destination: {
	    type: 'SQS',
	    queueURL: sqsQueueUrl
	    authenticationMode: 'IAM',
	    region: sqsRegion,
	},
  events: [
      { resourceTypeId: 'checkout',
		    types: [
		        'CheckoutPaymentRefunded',
		        'CheckoutPaymentRefundFailed',
		    ]
	    },
  ],
	messages: [
	    { resourceTypeId: 'order', types: [] }, // all order messages (e.g. OrderCreated, OrderPaymentAdded)
	    { resourceTypeId: 'payment', types: [] }, // all payment messages (transactions, state changes)
	],
  };
  return apiRoot
    .subscriptions()
    .post({ body: draft })
    .execute();
}

Build end-to-end Observability

Use both layers together for comprehensive control:

• Frontend (SDK Messages): guide shoppers, recover from transient issues, and maintain real-time UI integrity.
• Backend (Subscriptions and Events): automate post-checkout tasks and maintain consistency across systems.

Here are a couple of examples of this pairing in action:

• Frontend reacts to checkout_completed by redirecting and confirming that the Order has been received.
• Backend receives OrderCreated, and then triggers fulfillment and email workflows.

By combining Checkout Browser SDK Messages and backend Subscriptions, you can enable a resilient Checkout system that provides real-time visibility, immediate shopper guidance, and reliable backend synchronization across your commerce stack.

Key takeaways

• Checkout Messages provide real-time, Session-scoped feedback through the Browser SDK for immediate UI reactions and user guidance.
• Checkout Events are system-level notifications delivered through Subscriptions to trigger backend workflows like confirmations and integrations.
• Composable Commerce Messages track persistent entity changes across the platform for automation and cross-system synchronization.
• Handle frontend messages by using onInfo, onWarn, and onError callbacks to manage user experience and detect issues early.
• Subscribe to backend events by creating Subscriptions with the Events API to automate post-checkout processes.
• Combine both layers for end-to-end observability: frontend for immediate shopper guidance, backend for reliable workflow automation.

Test your knowledge