SfSkills Domains Docs GitHub

Home / admin / commerce-checkout-flow-design

commerce-checkout-flow-design

Use this skill when designing the checkout experience for a Salesforce B2B or D2C Commerce storefront — covering runtime model selection (LWR Managed Checkout vs Aura Flow Builder), cart and line-item requirements, payment option scoping, shipping rule definition, and guest vs.

Open the skill folder on GitHub

Commerce Checkout Flow Design

This skill activates when a practitioner or project team needs to define, scope, or document the checkout experience for a Salesforce B2B or D2C Commerce storefront before any implementation begins. It covers runtime model selection, UX step design, payment option scoping, shipping rule definition, and guest versus registered buyer experience planning. It does not cover implementation: Apex adapter code, CartCheckoutSession debugging, Extension Point class registration, or Flow Builder element configuration are handled by commerce-checkout-configuration.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

LWR Managed Checkout vs. Aura Flow Builder Checkout

Salesforce Commerce supports exactly two checkout runtime models. They are mutually exclusive — a store can only use one, and migrating between them requires a full storefront rebuild with no automated migration path.

LWR Managed Checkout (current strategic path for new stores):

Aura Flow Builder Checkout (supported, not recommended for new stores):

The design implication: every UX requirement that involves a custom step or custom data collection must be mapped to the available customization surface of the chosen runtime model before any work begins.

Checkout Step Sequence and Required Data

Regardless of runtime model, the underlying CartCheckoutSession moves through the same canonical steps: cart validation → inventory check → pricing recalculation → shipping method selection → tax calculation → payment authorization → order creation. Each step has required data that must be collected from the buyer and present in the cart record before that step can execute.

Design must account for:

Guest vs. Registered Buyer Experience

Guest checkout allows unauthenticated buyers to complete a purchase without creating an account. The platform does not have a user session to draw contact data from, which has significant design implications:

Registered buyer checkout can pre-populate address fields from the buyer's saved addresses if the storefront is wired to do so, but this is an opt-in design decision with its own UX implications (address book management, default address selection).

Payment Option Design Constraints

Salesforce Commerce does not have a native payment gateway connector. Every payment method requires an Apex Payment Adapter class implementing sfdc_checkout.CartPaymentAuthorize. Design must account for:

Common Patterns

Pattern: LWR Store with Single Payment Method (Credit Card)

When to use: Net-new D2C or B2B store on LWR template with a single payment gateway and no buyer approval workflow.

How it works:

  1. Confirm LWR template is selected or recommended. Document that Flow Builder checkout configuration has no effect on this store.
  2. Map the standard checkout steps: cart review → address entry (with explicit email/phone collection for guest users) → shipping method selection → order review → payment entry → confirmation.
  3. Identify the payment gateway and confirm client-side tokenization is available (Stripe Elements, Adyen Drop-in, Braintree Hosted Fields). Card data never enters Salesforce — only the token does.
  4. Define the decline UX: buyer is shown an error message and can re-enter payment details. The CartCheckoutSession is reset via the Checkout API; a new session starts from the payment step.
  5. Document that the shipping step triggers an async callout to the registered shipping/tax service. UX must show a loading indicator while rates are fetched.

Why not the alternative: Designing for Aura Flow Builder checkout on an LWR store produces configuration that has zero effect. Confirming the template type before any UX work begins prevents wasted design cycles.

Pattern: Aura Store with Guest and Registered Buyer Experience

When to use: Existing Aura store that needs to support both unauthenticated guest purchasers and registered account buyers with saved addresses.

How it works:

  1. Design two distinct checkout paths that share the same underlying Flow template but branch on buyer authentication state.
  2. For guest path: address step must include email and phone fields mapped explicitly to CartDeliveryGroup.Email and CartDeliveryGroup.Phone. Design a "same as shipping" toggle that copies address fields to WebCart billing fields.
  3. For registered path: pre-populate address from buyer's saved address book. Provide an "add new address" option that also writes to billing fields.
  4. Payment step is identical for both paths assuming the same payment method is supported for both. If PO is only available to registered buyers, add a conditional Flow branch that checks authentication state.
  5. Define the order confirmation experience for each path: guest buyers receive a confirmation email (requires email collection above); registered buyers see the order in their account order history.

Why not the alternative: Treating guest and registered paths as identical produces silent data gaps — null Contact fields on guest orders, missed email confirmations, and broken fulfillment integrations.

Decision Guidance

SituationRecommended ApproachReason
New store, greenfield projectUse LWR template with Managed CheckoutLWR is the strategic direction; new Extension Point model is more maintainable than custom Flow
Existing Aura store with heavy Flow investmentStay on Aura Flow Builder checkoutMigration requires full storefront rebuild; no automated migration path exists
Need guest checkoutDesign explicit email/phone collection in address stepPlatform does not derive these from guest session; null Contact fields result if omitted
Multiple payment methods requiredDesign each as a separate adapter; scope Apex development per methodEach method is a distinct Apex integration; payment method count directly drives development scope
B2B store with PO payment and approvalDesign PO as a distinct flow branch with approval stepPO payment has no real-time authorization; mixing it with card flow path creates state machine ambiguity
Shipping rates from external carrierDesign async loading UX with error fallbackShipping rate call is async; UX must handle latency and callout failure gracefully
Compliance or PCI-DSS concernsConfirm client-side tokenization for all card methodsNo raw card data may enter Salesforce; tokenization must happen at the client before any API call
D2C with free shipping thresholdDesign conditional free shipping as a cart-level ruleFree shipping thresholds are evaluated against cart total; design must specify the threshold and currency behavior

Step-by-step instructions for an AI agent or practitioner designing a Commerce checkout experience:

  1. Confirm or select the store template type. Establish definitively whether the store uses LWR (Managed Checkout) or Aura (Flow Builder checkout). If the store does not yet exist, make a runtime model recommendation using the decision table above. Document the chosen model as a locked constraint — all subsequent design steps depend on it.
  2. Map the buyer personas and authentication states. Define whether the checkout must serve guest buyers, registered buyers, or both. For each persona, document what identity and address data is available from the session and what must be explicitly collected in the UX. Flag guest checkout as requiring platform permission configuration that must happen before testing.
  3. Design the checkout step sequence. List every step in order. For each step, specify: what the buyer sees, what data they enter, what Salesforce object field that data maps to, and what platform action triggers at the end of the step. Explicitly mark steps that trigger async platform calls (shipping/tax) so the UX design accounts for loading states.
  4. Scope all payment methods. List every payment method the business requires at launch. For each: confirm client-side tokenization availability for card methods, identify whether a custom Apex adapter is required, and document the decline or failure UX. For B2B stores, determine whether PO payment needs a buyer approval branch.
  5. Define shipping rules. Specify the rate source (external carrier API, flat rate, free shipping), any free-shipping thresholds, and behavior for multiple delivery groups (split shipments). Document the external service endpoint if applicable and note that a callout failure must be handled gracefully in the UX.
  6. Identify design constraints and custom development scope. For the chosen runtime model, document what cannot be configured declaratively and will require custom Apex or LWC development. This is the handoff document to the implementation team — it defines the boundary between this design skill and commerce-checkout-configuration.
  7. Review design against the Well-Architected pillars. Confirm that security (PCI-DSS, guest user permissions, no raw card data), reliability (async callout failure handling, session reset on decline), and adaptability (runtime model lock-in implications) are explicitly addressed before handing off to implementation.

Review Checklist

Run through these before marking design work complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. Runtime model selection is permanent without a full rebuild — LWR stores cannot be converted to Aura stores and vice versa. There is no migration tool or hybrid mode. A team that begins design work assuming they can switch models later will face a complete rebuild if they change direction. The design phase is the last low-cost opportunity to make this decision.
  2. Guest checkout email and phone are not automatically populated — For unauthenticated buyers, Salesforce has no user session from which to derive contact data. If the UX design does not include explicit fields for email and phone mapped to CartDeliveryGroup, the resulting Order Contact is created with null values and no error is thrown. This breaks order confirmation emails and fulfillment integrations silently.
  3. Billing address must be explicitly mapped from the shipping address — The "same as shipping" billing address pattern common in consumer UX does not happen automatically. The design must include explicit logic to copy BillingStreet, BillingCity, BillingPostalCode, BillingState, and BillingCountry from the delivery address to the WebCart record. Missing billing fields produce an OrderSummary with a null billing contact at order creation.
  4. Shipping and tax steps trigger a single combined async callout — From a UX design perspective, shipping method selection and tax calculation are not two separate user-visible steps that can be independently retried. They share one async platform job. A design that shows separate "calculate shipping" and "calculate tax" buttons does not map to how the platform actually works and will require significant workarounds to implement.
  5. Extension Points and Flow Builder checkout are mutually exclusive configuration surfaces — LWR stores using Managed Checkout cannot use Flow Builder to add custom checkout steps, and Aura stores using Flow Builder cannot use Extension Point classes for custom behavior. Designs that reference both surfaces as options for the same store are not implementable.

Output Artifacts

ArtifactDescription
Runtime model selection documentConfirmed choice of LWR Managed Checkout or Aura Flow Builder with rationale and implications
Checkout step mapOrdered list of buyer-facing steps with Salesforce field mappings and async trigger points
Guest vs. registered experience matrixDocuments what differs per buyer type, required fields, and platform permissions needed
Payment options design specLists all payment methods, tokenization approach, decline UX, and custom Apex scope per method
Shipping rules design specRate source, free shipping rules, multi-delivery-group behavior, and callout failure UX
Design constraints documentWhat the chosen runtime model cannot do declaratively; handoff doc to implementation team

Package files