Skip to main content

Checkout

The checkout domain covers everything from adding items to a cart through to completing an order and processing payment. It is split across two types of services: the checkout service (which owns the flow) and payment provider services (which handle PSP communication).

Cart operations​

The checkout service exposes GraphQL mutations for managing the shopping cart:

  • cartLineItemsAdd: add products to the cart by SKU and quantity. Creates a new cart automatically if none exists.
  • cartLineItemsUpdate: change the quantity of existing line items.
  • cartLineItemsRemove: remove line items from the cart.
  • cartUpdate: apply configuration changes such as setting the customer email, billing address, shipping address, shipping method, or payment method.
  • cartDiscountCodeAdd / cartDiscountCodeRemove: manage discount codes on the cart.

All cart mutations use the @requiresSession directive, which creates a guest session automatically when no session exists.

API extensions​

The checkout service registers commercetools API extensions that run automatically when resources are created or updated. These extensions handle defaults that would otherwise require extra roundtrips from the frontend:

  • Cart create: copies the customer's default addresses and email onto the cart. For B2B carts, it uses the business unit's addresses instead.
  • Cart update: auto-selects a default shipping method when a shipping address is set but no method has been chosen.
  • Order create: generates a unique order number, ensures the customer email is set, and applies the default order type.
  • Payment create: transitions new payments to the PaymentInitial state.

Order creation​

The checkoutComplete mutation validates the cart and creates an order from it. The order extension fires during creation to assign an order number and fill in any missing fields. On success, the mutation returns the order ID and order number.

Payment routing​

When the frontend calls createPayment, the checkout service creates a Payment object on the order and delegates the actual transaction to the appropriate payment provider service based on the selected payment method. The provider starts a transaction with the PSP and returns a redirect URL for the customer.

See Payment architecture for the full payment flow, state machine, and REST endpoint contract.

Event subscriptions​

The checkout service subscribes to commercetools messages for asynchronous processing:

  • PaymentStatusStateTransition: when a payment reaches success, the checkout service checks whether all payments on the order cover the total amount and marks the order as paid.
  • OrderStateChanged: when an order is confirmed, the service sends a confirmation email through the notification service.