Documentation
Learning PathModule

Extend the Checkout functionality

Implement real-world features for complex checkout scenarios.

Ask about this Page
Copy for LLM
View as Markdown

After completing this page, you should be able to:

  • Implement custom Order numbers in Checkout Sessions.

  • Apply advanced Checkout features to complex business scenarios.

  • Configure multiple Shipping Methods for single-Order fulfillment.

Commercetools Checkout offers advanced features that let you extend and customize the checkout experience to meet complex business requirements. On this page, you'll learn how to implement the following functionalities:

  • Custom Order numbers
  • Multiple Shipping Methods
  • Skip default Checkout pages

Custom Order numbers

Custom Order numbers let you assign your own Order reference—like internal purchase order (PO) numbers or external system IDs—directly in a Checkout Session. This ensures that the commercetools Order uses the same identifier that you need across your ecosystem, preventing the need for post-creation updates that can introduce delays.

Without custom Order numbers, you would need to create the Order first, and then apply the setOrderNumber update action. This two-step process introduces latency issues when redirecting users to confirmation pages like example.com/checkout/success/{orderNumber}. Custom Order numbers prevent this delay by setting the identifier during the Checkout Session creation.

Set a custom Order number

Include the futureOrderNumber field in the metadata object when creating a Checkout Session. This value becomes the orderNumber in the resulting Order entity.

Handle duplicate Order numbers

Order numbers must be unique across your Project. If two Sessions try to finalize with the same futureOrderNumber, then the second Session fails and no Order is created. Implement collision handling in your Order number generation logic to prevent such types of scenarios.

Use cases

  • Cross-platform consistency: match internal and external IDs across invoices, tracking systems, and payment service providers (PSPs).
  • Embedded metadata: include store codes, regional identifiers, or date stamps within the Order number for easier reconciliation.

Use Multiple Shipping Methods

Multiple Shipping Methods let Customers apply different fulfillment options for items within a single Order, such as an in-store pickup for one item and express delivery for another. This capability supports complex Customer preferences without forcing separate transactions.

The Commercetools Checkout Payment Only mode supports using multiple Shipping Methods when you set a Cart's shippingMode to Multiple during creation. This architectural decision separates shipping configuration from Payment processing, giving you full control over the fulfillment logic before entering the Payment flow.

Real-world scenario

Consider a Customer who wants to purchase a laptop and a vacuum cleaner. They want the laptop immediately via in-store pickup, but need the vacuum delivered by express courier. The multiple Shipping Methods feature can accommodate both preferences in a single Checkout Session, improving conversion by preventing the friction of separate orders.

Prerequisites

  • Set the Cart's shippingMode as Multiple before creating the Checkout Session.
  • Assign Shipping Methods to individual Line Items by using the Cart API.
  • Use Payment Only mode. This is because the Complete Checkout mode handles shipping configuration internally.

Skip Default Checkout Pages

By default, commercetools Checkout displays a Payment success page and a Payment error page. While these out-of-the-box pages work for standard implementations, custom frontends, mobile apps, and headless architectures often require full control over the post-payment experience.

Skipping default pages lets you perform the following customizations:

  • Display custom confirmation screens with branded messaging and cross-sell opportunities.
  • Trigger backend workflows like Order fulfillment or analytics before showing confirmation.
  • Handle Payment failures with custom error messages, retry flows, or alternative payment method suggestions.

Configure page skipping

Set the skipPaymentSuccessPage and skipPaymentErrorPage configuration properties when initializing the Checkout SDK with the checkoutFlow method.
ctc('checkoutFlow', {
  projectKey: '{project-key}',
  region: '{region}',
  sessionId: '{session-id}',
  skipPaymentSuccessPage: false,
  skipPaymentErrorPage: true,
});
The page skipping feature works only with the checkoutFlow method. The Payment Only mode doesn't support skipping default pages.

Handle checkout completion

When skipping pages, you're responsible for detecting Payment results and responding appropriately. Implement Checkout Message handlers to perform the following actions:
  • Detect checkout completion events.
  • Route users to appropriate confirmation or error pages.
  • Display Order details or recovery options based on Payment status.

Key takeaways

  • Custom Order numbers let you set identifiers during Checkout Session creation, preventing post-creation update latency when redirecting to confirmation pages.
  • Order numbers must be unique across your Project; duplicate futureOrderNumber values cause the second Session to fail.
  • Multiple Shipping Methods enable different fulfillment options per Line Item within a single Order, improving Customer experience for complex purchases.
  • Configure multiple Shipping Methods by setting the Cart's shippingMode as Multiple before creating a Checkout Session in Payment Only mode.
  • Skip default Checkout pages to implement custom post-Payment experiences, but handle Checkout Messages to detect Payment results and route users appropriately.
  • Page skipping works only with the checkoutFlow method, not with Payment Only mode.

Test your knowledge