Skip to content

Execution Flows

Step-by-step checkout flows including shipping save, payment processing, order placement, and guest checkout.

Flow 1: Shipping Information Save

When the customer completes the shipping step, the frontend calls the shipping information API to save the address and selected shipping method. This triggers totals recalculation and returns available payment methods.

Entry Point

POST /V1/carts/mine/shipping-information

Or: ShippingInformationManagementInterface::saveAddressInformation()

Execution Steps

1. Validate Shipping Information

The ShippingInformationManagement validates the incoming data structure and ensures shipping and billing addresses are properly formatted.

2. Load and Validate Quote

Loads the quote by cart ID. Validates the quote is active, has items, and is not already converted to an order.

$quote = $this->quoteRepository->getActive($cartId);

3. Process Shipping Address

Assigns shipping address to quote. For virtual quotes (downloadable only), this step is skipped.

  • - Validates country/region
  • - Saves customer address if requested
  • - Sets shipping method code and carrier code

4. Process Billing Address

Sets billing address on quote. If "same as shipping" is selected, billing address is copied from shipping.

5. Validate Shipping Method

Validates the selected shipping method is available for the given address. Throws InputException if method is invalid.

6. Collect Totals

Triggers full quote totals collection with the new shipping method applied.

$quote->collectTotals();
$this->quoteRepository->save($quote);

7. Return Payment Details

Returns PaymentDetailsInterface containing available payment methods and updated totals.

Event Dispatched

The quote save triggers sales_quote_save_after which updates the checkout session quote ID.

Flow 2: Order Placement

The order placement flow handles payment information saving and order creation. This is the most critical flow in checkout, with multiple validation and rate limiting steps.

Entry Point

POST /V1/carts/mine/payment-information

Or: PaymentInformationManagementInterface::savePaymentInformationAndPlaceOrder()

Execution Steps

1. Rate Limit Check

The PaymentProcessingRateLimiterInterface checks for abuse. Default implementation uses CAPTCHA validation.

Security: Rate limiting prevents brute-force attacks on payment processing.

2. Save Payment Information

Calls savePaymentInformation() to store payment method on quote. This also updates the billing address.

3. Validate Agreements

If checkout agreements are enabled, validates that all required agreements have been accepted.

$this->agreementsValidator->isValid($agreementIds);

4. Place Order via CartManagement

Delegates to CartManagementInterface::placeOrder() from the Quote module.

$orderId = $this->cartManagement->placeOrder($cartId);

5. Quote to Order Conversion

CartManagement converts quote items to order items, creates the order entity, and processes payment authorization/capture.

  • - Quote items → Order items
  • - Quote addresses → Order addresses
  • - Payment method → Order payment
  • - Inventory reservation

6. Clear Checkout Session

After successful order placement, the checkout session is cleared and order confirmation data is stored.

7. Return Order ID

Returns the new order ID (entity_id). Frontend then redirects to success page.

On Success

  • - Order created with pending status
  • - Order confirmation email queued
  • - Quote marked as inactive
  • - Inventory reserved

On Failure

  • - Exception thrown to frontend
  • - Quote remains active
  • - Payment failed email sent (if configured)
  • - Rate limit counter incremented

Flow 3: Guest Checkout

Guest checkout uses masked cart IDs and dedicated Guest* interfaces for security. The flow is similar to authenticated checkout but requires email address and uses public endpoints.

Entry Point

POST /V1/guest-carts/:cartId/payment-information

Or: GuestPaymentInformationManagementInterface::savePaymentInformationAndPlaceOrder()

Key Differences from Customer Checkout

1. Masked Cart ID

Guest carts use a masked ID (UUID) instead of the actual quote entity_id. This prevents ID enumeration attacks.

// Masked: "xyzABC123..."
$quoteIdMask = $this->quoteIdMaskFactory->create()->load($cartId, 'masked_id');
$quoteId = $quoteIdMask->getQuoteId();

2. Email Required

Guest checkout requires email address in the API call. This is used for order confirmation and to check if the customer already exists.

3. No Customer Association

The order is created with customer_is_guest = 1. No customer entity is created or linked.

4. Anonymous Resource Access

Guest endpoints use <resource ref="anonymous" /> in webapi.xml, allowing unauthenticated access.

Account Creation Option

If "Create Account" is selected during guest checkout, the system creates a customer account after order placement and links the order to the new customer.

Flow 4: Totals Calculation

The totals calculation flow is called dynamically as the customer enters address information. It provides real-time updates of shipping costs, taxes, and grand total.

Entry Point

POST /V1/carts/mine/totals-information

Or: TotalsInformationManagementInterface::calculate()

Execution Steps

1. Load Quote

Loads the active quote for the cart ID.

2. Apply Address for Estimation

Temporarily applies the provided address to the quote's shipping address for totals calculation purposes.

3. Set Shipping Method (if provided)

If shipping method is provided, applies it to the quote for accurate shipping cost calculation.

4. Collect Totals

Triggers the Quote totals collectors chain to calculate all totals.

$quote->collectTotals();

5. Return Totals

Returns TotalsInterface with subtotal, shipping, tax, discount, and grand total.

Performance Note

Totals calculation is called frequently during checkout (on address change, shipping method change). The Quote module caches calculated totals to avoid redundant calculations within the same request.

Checkout Session Lifecycle

Session Start

  • Quote created or loaded
  • Quote ID stored in session
  • CustomerData sections loaded

During Checkout

  • Quote updated via API calls
  • Session maintains state
  • Browser localStorage caches data

After Order

  • Quote marked inactive
  • Session stores last order ID
  • New quote created on next cart action