Commerce Checkout Configuration

This skill activates when a practitioner needs to configure or debug the end-to-end checkout experience for a Salesforce B2B or D2C Commerce store — covering CartCheckoutSession state orchestration, payment gateway integration via Apex adapters, shipping and tax API wiring, guest checkout requirements, and order summary creation. It does not cover CPQ quoting, post-fulfillment Order Management flows, or third-party checkout-as-a-service integrations outside Salesforce.

---

Before Starting

Gather this context before working on anything in this domain:

• Store template type. LWR stores use Managed Checkout (a platform-orchestrated checkout experience). Aura stores use a Flow Builder-driven checkout flow. These are mutually exclusive runtime models with different configuration surfaces.
• Payment gateway contract. Determine which payment gateway the merchant uses (e.g., Stripe, Adyen, Braintree). A custom Apex class implementing sfdc_checkout.CartPaymentAuthorize is the only supported integration path.
• Guest vs. authenticated. Guest checkout requires specific shipping address fields (email, phone) and additional site guest user permission set assignments. Without these, order creation fails silently.
• Shipping and tax service availability. Shipping rates and tax amounts are fetched in a single async API call when the buyer enters a delivery address. The external endpoint must respond within the platform's async callout timeout window. A failed callout leaves CartCheckoutSession in an error state.
• Billing address on cart. The BillingStreet, BillingCity, BillingPostalCode, BillingCountry, and BillingState fields on the WebCart record must be set before the final order creation step executes. Missing fields cause OrderSummary to be created with a null billing contact — there is no error thrown.

---

Core Concepts

CartCheckoutSession State Machine

Checkout in Salesforce Commerce is modeled as a CartCheckoutSession record that advances through a defined set of sequential states. The canonical state sequence is:

1. Start — session created, cart validated
2. Inventory — inventory availability checked for all line items
3. Pricing — prices recalculated against active price books
4. Shipping — available shipping methods fetched from an external service or custom Apex
5. Tax — tax amounts calculated, applied to cart totals
6. Payment Authorization — payment gateway called to authorize the selected payment instrument
7. Order Creation — WebCart converted to an Order and OrderSummary

Each state transition is atomic. If a state fails (e.g., an inventory check returns insufficient stock), the session pauses in that state and exposes an error on the CartValidationOutput record linked to the session. The practitioner must resolve the underlying issue and re-trigger the state before checkout can continue.

LWR stores use the Commerce Checkout REST API (/commerce/webstores/{id}/checkouts) to move the session forward programmatically. Aura stores drive the same state machine through a declarative checkout Flow that calls the Cart Calculate API internally.

LWR Managed Checkout vs. Aura Flow Builder Checkout

These are two distinct runtime models that share the same underlying CartCheckoutSession object but expose different configuration surfaces:

• LWR (Managed Checkout): Configured through the Commerce App in Setup. Platform manages session state progression automatically. Custom behavior is injected via Extension Points (Apex classes) registered against named extension point contracts. No Flow Builder involvement. This is the current strategic path for new stores.
• Aura (Flow Builder Checkout): Configured using the Checkout Flow in the storefront Experience Builder. A standard Flow template ships with the managed package; merchants clone and modify it. State transitions are modeled as Flow elements. This path is still supported but not recommended for new implementations.

Both models converge on the same Order and OrderSummary objects at completion.

Apex Payment Adapter

Salesforce Commerce does not connect to a payment gateway directly. All payment authorization is routed through a developer-authored Apex class that implements the sfdc_checkout.CartPaymentAuthorize interface. The platform calls authorizePayment(CartExtension.CartPaymentAuthorizationRequest request) and expects a CartExtension.CartPaymentAuthorizationResponse in return.

The adapter class is responsible for:

• Extracting the payment token from the request (tokenized by the client-side payment component before checkout submission)
• Calling the gateway's authorization API via Http callout
• Mapping the gateway response (approved, declined, error) back to the Commerce response type
• Writing any gateway-specific reference data (authorization code, transaction ID) to a custom field on the order before returning

A declined authorization must return a response with setAuthorized(false) — not throw an exception. Throwing an exception from the adapter leaves the CartCheckoutSession in an unrecoverable error state that requires manual session reset.

Shipping and Tax Integration

Shipping and tax are evaluated together in a single async callout triggered when the buyer selects or changes their delivery address. Salesforce calls the registered external shipping/tax service and expects a structured response containing available shipping methods (with prices) and tax line items.

Two integration paths exist:

• Salesforce-managed integration: For supported carriers and tax engines (Avalara, Vertex), configuration is point-and-click in Commerce Setup. Salesforce handles the callout, response parsing, and cart field updates.
• Custom Apex shipping/tax provider: For unsupported carriers or custom tax logic, a developer implements a class that extends sfdc_checkout.CartShippingCharges and another that extends sfdc_checkout.CartTaxes. These classes are registered as extension points and called synchronously within the async job.

---

Common Patterns

Pattern: Apex Payment Adapter with Tokenized Card

When to use: Any store that requires credit/debit card payment where the gateway is not natively supported by Salesforce Commerce.

How it works:

1. The storefront renders the gateway's client-side payment component (e.g., Stripe Elements). The component tokenizes the card and stores the token in a hidden field or a custom payment method record.
2. When the buyer submits payment, the token is passed to the checkout session via the paymentMethod payload in the Commerce Checkout API or the Flow element.
3. The platform calls the registered Apex adapter's authorizePayment method with a CartPaymentAuthorizationRequest that includes the token.
4. The adapter retrieves the token, calls the gateway's charge or authorize endpoint via Http, and maps the response to CartPaymentAuthorizationResponse.
5. On success, the adapter sets setAuthorized(true) and optionally sets a reference field on the cart before returning.

Why not the alternative: Storing raw card data in Salesforce fields violates PCI-DSS and is not possible on the platform. Tokenization at the client side before any Salesforce data layer involvement is the only compliant approach.

Pattern: Guest Checkout with Required Address Fields

When to use: B2B or D2C stores that allow unauthenticated buyers to complete an order without creating an account.

How it works:

1. Enable Guest Browsing and Guest Checkout in the store's Experience Site settings.
2. Assign the Guest User profile the required Commerce permissions: WebCart, CartItem, CartDeliveryGroup, WebOrder, and CartCheckoutSession object access.
3. At address entry, the storefront component must collect and populate Email and Phone on the CartDeliveryGroup shipping address. These are not automatically populated from a user session because no session exists.
4. Before order creation, ensure BillingStreet, BillingCity, BillingPostalCode, BillingState, and BillingCountry are set on WebCart. Map these from the shipping address if the buyer indicates billing and shipping are the same.
5. The Order and Contact are created from these field values. Missing fields do not error — they silently produce incomplete records.

Why not the alternative: Relying on the platform to derive contact data from the guest session produces null Contact records on the Order. The guest user has no profile email that Salesforce can automatically populate into order fields.

---

Decision Guidance

Situation	Recommended Approach	Reason
New store on LWR template	Use Managed Checkout with Extension Points	Platform-managed state progression; less custom code; strategic path
Existing Aura store with custom Flow checkout	Keep Flow Builder checkout; do not migrate mid-project	Migration requires full storefront rebuild; parity is not automatic
Supported payment gateway (e.g., Stripe, Adyen)	Implement Apex Payment Adapter with client tokenization	No native gateway connector exists; adapter is the only supported path
Tax via Avalara or Vertex	Use native Commerce Setup integration	Salesforce manages the callout contract and cart field mapping
Custom carrier rate logic	Extend sfdc_checkout.CartShippingCharges in Apex	Provides structured integration without breaking session state
Guest checkout needed	Enable in Site Settings and populate email/phone on CartDeliveryGroup	Platform does not derive these from unauthenticated session
Order billing address missing	Set billing fields on WebCart before order creation step	OrderSummary is created from WebCart at that moment; no retry path

---

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner configuring or debugging Commerce checkout:

1. Confirm the store template type. Navigate to Commerce Setup and identify whether the store uses LWR (Managed Checkout) or Aura (Flow Builder checkout). This determines every subsequent configuration surface. Do not assume — the wrong surface produces changes that have no effect.
2. Verify CartCheckoutSession state and errors. Query CartCheckoutSession and the associated CartValidationOutput records in the org to identify which state the session is paused in and what error is recorded. Fix the underlying cause (inventory, shipping, tax, payment) before adjusting configuration.
3. Configure the shipping and tax provider. In Commerce Setup, under Shipping and Tax, register the external service endpoint or verify the Apex extension point class is deployed and assigned. Confirm the external endpoint responds within the platform callout timeout. Run a test checkout to trigger the async shipping/tax job and inspect the resulting CartDeliveryGroupMethod records.
4. Deploy and register the Apex Payment Adapter. Write or review the class implementing sfdc_checkout.CartPaymentAuthorize. Deploy to the org, then register it in Commerce Setup under Payment. Verify the adapter returns setAuthorized(false) on declines rather than throwing exceptions.
5. Set billing address fields before order creation. Confirm that the storefront component or Flow element populates BillingStreet, BillingCity, BillingPostalCode, BillingState, and BillingCountry on WebCart before the final order creation step. Query a test WebCart record after address entry to verify.
6. Validate guest checkout field population. For guest-enabled stores, confirm that Email and Phone are set on CartDeliveryGroup at address entry time. Complete a guest checkout end to end in a test environment and query the resulting Order Contact record to verify it is not null.
7. Review the resulting Order and OrderSummary. After a successful test checkout, inspect the Order, OrderSummary, and OrderDeliveryGroup records for correct billing contact, shipping method, and line item pricing. Compare against the WebCart state at order creation time.

---

Review Checklist

Run through these before marking work in this area complete:

• Store template type confirmed (LWR Managed Checkout or Aura Flow Builder)
• CartCheckoutSession state machine tested end to end in a scratch or sandbox org
• Apex Payment Adapter deployed, registered in Commerce Setup, and tested with decline scenario
• Shipping and tax provider registered; CartDeliveryGroupMethod records verified after address entry
• Billing address fields set on WebCart before order creation; OrderSummary billing contact is non-null
• Guest checkout tested end to end; email and phone present on resulting Order Contact
• All Apex adapter callouts mocked in unit tests; no raw card data stored in any Salesforce field

---

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Billing address must be set on WebCart before order creation — If BillingStreet, BillingCity, BillingPostalCode, BillingState, and BillingCountry are not populated on the WebCart record at the moment the Order is created, the resulting OrderSummary will have a null billing contact. No error or warning is thrown. The only fix is to prevent the issue upstream by ensuring the storefront or Flow sets these fields before the order creation state executes.
2. Guest checkout requires email and phone on CartDeliveryGroup shipping address — For unauthenticated buyers, Salesforce has no profile email or phone to draw from. If the storefront does not explicitly collect and write Email and Phone to CartDeliveryGroup, the resulting Contact record on the Order is created with null values. This breaks downstream processes such as order confirmation emails and fulfillment system integrations.
3. Payment adapter exceptions leave CartCheckoutSession unrecoverable — If the Apex Payment Adapter throws an unhandled exception instead of returning setAuthorized(false), the CartCheckoutSession enters an error state that cannot be resolved by retrying checkout. The session must be reset via the Commerce Checkout API (DELETE /checkouts/{id}) and a new session started. Train gateway error handling to always return a structured response, never throw.
4. Managed Checkout Extension Points and Flow Builder checkout are mutually exclusive — LWR stores register custom behavior via Apex Extension Point classes in Commerce Setup. Configuring a checkout Flow in Experience Builder has no effect on an LWR store. Conversely, Extension Point classes have no effect on Aura stores. Mixing configuration from both surfaces in the same store produces silently ignored settings.
5. Shipping and tax callout failure pauses the session silently — If the external shipping/tax service returns an error or times out, the CartCheckoutSession pauses at the Shipping state without surfacing a user-visible error message unless the storefront is explicitly coded to read CartValidationOutput. Merchants often interpret this as a UI bug rather than a backend callout failure. Always inspect CartValidationOutput records linked to the session when debugging a stuck checkout.

---

Output Artifacts

Artifact	Description
CartCheckoutSession record	Platform record tracking current checkout state; inspect for errors in CartValidationOutput
Apex Payment Adapter class	Custom Apex implementing sfdc_checkout.CartPaymentAuthorize; deployed and registered in Commerce Setup
CartDeliveryGroupMethod records	Created after shipping provider responds; confirm correct rates are returned
Order and OrderSummary records	Final purchase records; verify billing contact, line items, and payment authorization reference
Commerce Setup configuration	Registered shipping/tax provider and payment adapter; the authoritative configuration source

---

Related Skills

• commerce-store-setup — Configure the store catalog, entitlements, and price books before checkout is reached
• apex-callout-patterns — Best practices for writing reliable HTTP callouts from Apex, relevant to payment adapter and shipping integrations
• order-management-integration — Post-checkout fulfillment flows using Salesforce Order Management