SfSkills Domains Docs GitHub

Home / admin / commerce-checkout-configuration

commerce-checkout-configuration

Use this skill when configuring Salesforce B2B or D2C Commerce checkout: payment methods, shipping/tax integration, guest checkout, order summary setup, and CartCheckoutSession state orchestration. Trigger keywords: checkout flow, payment adapter, shipping tax integration, guest checkout, order summary, CartCheckoutSession, Managed Checkout, Commerce checkout flow. NOT for deciding the checkout design before build (LWR vs Aura) — use admin/commerce-checkout-flow-design. NOT for writing the CommercePayments adapter class — use apex/commerce-payment-integration.

Open the skill folder on GitHub

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:

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:

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:

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:

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

SituationRecommended ApproachReason
New store on LWR templateUse Managed Checkout with Extension PointsPlatform-managed state progression; less custom code; strategic path
Existing Aura store with custom Flow checkoutKeep Flow Builder checkout; do not migrate mid-projectMigration requires full storefront rebuild; parity is not automatic
Supported payment gateway (e.g., Stripe, Adyen)Implement Apex Payment Adapter with client tokenizationNo native gateway connector exists; adapter is the only supported path
Tax via Avalara or VertexUse native Commerce Setup integrationSalesforce manages the callout contract and cart field mapping
Custom carrier rate logicExtend sfdc_checkout.CartShippingCharges in ApexProvides structured integration without breaking session state
Guest checkout neededEnable in Site Settings and populate email/phone on CartDeliveryGroupPlatform does not derive these from unauthenticated session
Order billing address missingSet billing fields on WebCart before order creation stepOrderSummary is created from WebCart at that moment; no retry path

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:

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

ArtifactDescription
CartCheckoutSession recordPlatform record tracking current checkout state; inspect for errors in CartValidationOutput
Apex Payment Adapter classCustom Apex implementing sfdc_checkout.CartPaymentAuthorize; deployed and registered in Commerce Setup
CartDeliveryGroupMethod recordsCreated after shipping provider responds; confirm correct rates are returned
Order and OrderSummary recordsFinal purchase records; verify billing contact, line items, and payment authorization reference
Commerce Setup configurationRegistered shipping/tax provider and payment adapter; the authoritative configuration source

Package files