Browser SDK enhancements

The Checkout Browser SDK received numerous updates throughout 2025.

Configuration properties

• Skip payment pages: the skipPaymentSuccessPage and skipPaymentErrorPage properties were added in April 2025. These properties are independent of each other, so you can pass just one of them, or both. This allows you to bypass default success and error pages, provide custom post-payment experiences, integrate payment results directly into your application flow, and reduce unnecessary page transitions.
• Tax display control: the showTaxes property was replaced with the more flexible tax property in July 2025. The new tax property structure provides finer control over tax display formatting with {display: true} to show tax information from Composable Commerce in the price summary.
• Extension error messages: the showExtensionErrorMessages property was added in July 2025. If the address property inside the object is set as true, then address-related extension error messages are shown in the UI. Otherwise, a generic error message will be shown.

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

checkoutFlow({
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  tax:{
    display: true
  },
  skipPaymentSuccessPage: true,
  skipPaymentErrorPage: true,
  showExtensionErrorMessages:{
    address: true
  },
  // Handle results through messages instead
});

Message handling improvements

• Payment Connector Error → ConnectorError
• Payment Methods Received → PaymentIntegrationsReceived
• Multiple Payment Method Containers → MultiplePaymentIntegrationContainers
• No Payment Methods → NoPaymentIntegrations
• Payment Method Not Available → PaymentIntegrationNotAvailable
• Payment Method Loading → PaymentIntegrationLoading
• Payment Method Loading Error → PaymentIntegrationLoadingError
• Payment Method Loaded → PaymentIntegrationLoaded
• Payment Method Selected → PaymentIntegrationSelected
• Payment Method Selection Confirmation → PaymentIntegrationSelectionConfirmation
• Payment Method Selection Confirmation Failed → PaymentIntegrationSelectionConfirmationFailed
• Payment Started → PaymentStarted

• Payment Verification Started -> Order Verification Started: it signals the beginning of verification process.
• Payment Verification Timeout -> Order Verification Timeout: it is triggered when order verification takes too long.
• Order Verification Retry Error: indicates an error during verification retry.

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

retryOrderVerification();

Discount code handling

When a discount code becomes invalid or doesn't apply to the current Cart contents, several things happen automatically: the code is removed from the Cart, a Message is sent to notify your application, and pricing updates to reflect the code removal. This allows you to inform customers about the change and explain why their discount code was removed.

You can subscribe to this message to provide feedback to customers when discount codes are automatically removed from the Cart. By subscribing to this message, you can provide clear feedback to customers when discount codes are automatically removed, maintaining transparency throughout the checkout process:

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

checkoutFlow({
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  onWarn: (message) => {
    if (message.code === 'not_applicable_discount_code_removed') {
      const { cartId, discountCode } = message.payload;
      // Display notification to customer
      displayNotification(`Discount code ${discountCode} is no longer applicable`);
      // Update cart display
      updateCartDisplay();
    }
  }
});

Style customization

Three new styling variables were added:

• --button-outline: allows you to customize the primary button’s border and outline color to match your brand guidelines.
• --button-hover: allows you to set the primary button’s background color when customers hover over it, creating interactive visual feedback.
• --spinner: allows you to customize the loading spinner’s color to align with your overall color scheme.

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

checkoutFlow({
  projectKey: '{projectKey}',
  region: '{region}',
  sessionId: '{sessionId}',
  styles: {
    '--button-outline': '#007bff',
    '--button-hover': '#0056b3',
    '--spinner': '#007bff'
  }
});

Test your knowledge