Avoid Common Misconfigurations

Diagnose and resolve common configuration issues across cart, checkout, pricing, and account-based flows.

  • Using Custom UI Before Checkout Completes

    Problem: Custom UI components invoke before previous Checkout API completes (still returns 202).

    Impact: Components use incomplete or inconsistent data.

    Solution: Disable or hide custom components until API returns 200 OK.

  • Executing Custom Apex Prematurely

    Problem: Custom Apex calls run without verifying Checkout API completed.

    Impact: Logic consumes incomplete data, leading to inconsistent results.

    Solution: Poll GET /checkouts until you receive 200 OK, then execute custom logic.

  • Invalid Custom Payment Configuration

    Problem: Custom payment (like Cash on Delivery) doesn't meet API expectations.

    Impact: API returns "Looks like the payment method isn't authorized" error.

    Requirements — Place Order API:

    • Provide Purchase Order Number, OR
    • Provide valid PaymentMethod and PaymentGroup on WebCart

    Place Order Action API:

    • Provide Purchase Order Number, OR
    • Provide valid PaymentGroup on WebCart AND
    • Verify: TotalAuthAndSaleAmount + PendingAuthAndSaleAmount = GrandTotalAmount (or FirstPymtGrandTotalAmount for subscriptions)

  • Concurrent Cart Updates

    Problem: Custom Apex modifies cart while Checkout API is in progress.

    Impact: Cart state mismatch causes "cart is currently in use" error.

    Solution: Avoid concurrent operations on the cart. Wait for Checkout APIs to return 200 OK before running custom code that modifies cart.

  • Price Book Mismatch on Order

    Problem: Custom logic sets or updates Order.Pricebook2Id, creating mismatch with order products.

    Impact: Validation fails with "Order Products must have a Price Book Entry that belongs to the Price Book related to the parent Order" error.

    Solution:

    • Make sure that Order.Pricebook2Id matches the price book used by all order products, OR
    • Turn on the Enable Multiple Price Books for Orders setting

  • Billing Address Override

    Problem: Custom Apex updates billing address before user enters checkout or before shipping address is provided.

    Impact: Payment details become invalidated, billing address is overridden or lost.

    Solution:

    • Use Checkout Payment API to set billing address, OR
    • Update billing address only after checkout reaches payment stage

  • Duplicate Orders and Order Summaries

    Problem: Custom Record-After-Save flow (like Create Order Summary) runs on Order object, automatically creating Order Summary when Order record is created.

    Impact:

    • Cart isn't properly closed
    • OrderIngestionJob retries processing
    • Creates duplicate Orders and Order Summaries

    Solution: Configure the flow to exclude B2B web stores. Add conditions so the flow doesn't run for B2B checkout scenarios.

  • Order Summary Failure Without Payment Reversal

    Problem: Place Order Actions API succeeds but asynchronous Order Summary creation fails (only affects Place Order Actions API).

    Impact: Order is placed but Order Summary creation fails, leaving transaction inconsistent. Payment remains captured and isn't automatically refunded.

    Solution: Turn on the CheckoutReverseAuthEnabled org permission to reverse payments if checkout fails or is cancelled. Note: Refunds can incur additional charges from the payment provider.

  • Missing Pay Now Template

    Problem: Pay Now template doesn't appear when creating new store in Salesforce Foundation org.

    Impact: Can't access Pay Now template during store creation.

    Solution: Add free Salesforce add-on Payments license to enable Pay Now template.

  • Phone Number Validation Errors

    Problem: Checkout fails with "Select your country from the dropdown menu, and then enter your phone number" or unexpected phone number format changes.

    Impact:

    • Validation fails for unsupported country codes (like Costa Rica)
    • Phone numbers normalize to E164 format, removing hyphens and formatting

    Solution: Enable CheckoutSkipPhoneValidation org permission to bypass validation if default behavior doesn't meet requirements.

  • Invalid Checkout Session Status

    Problem: Custom flows invoke Sfdc_Checkout.CheckoutOrderService.cartToOrderSummary while Place Order Actions API is enabled.

    Impact: Method expects CheckoutSessionStatus to be PENDING_CLOSED but actual status is ACTIVE, causing "Invalid checkout session status" error.

    Solution:

    • Switch to Commerce Webstore Checkout Orders API, OR
    • Use Commerce Webstore Checkout Place Order Action API instead of custom Apex method

  • Asynchronous Payment Providers with Place Order API

    Problem: Payment providers confirm payments asynchronously but you're using Place Order V1.

    Impact: Orders are created regardless of payment status. Payment confirmation occurs later, potentially after order creation without successful payment.

    Solution: Switch to Commerce Webstore Checkout Place Order Action API, which creates orders only after receiving payment confirmation.

  • Concurrent Order Retrieval After Order Placement

    Problem: Custom Apex retrieves orders immediately after invoking Place Order API.

    Impact: Order creation occurs asynchronously. Concurrent requests cause record locking issues and failures in order creation.

    Solution: Avoid running custom logic that queries or modifies orders concurrently with asynchronous cart-to-order process.

  • Long-Running Callouts in Extensions

    Problem: Extensions include callouts taking longer than 2 seconds.

    Impact: Total processing time exceeds limits (over 5 seconds), causing integration retries. Multiple processes contend for same cart resources.

    Solution:

    • Make sure that callouts complete within 2 seconds, OR
    • Don't invoke GET /checkouts prematurely—allow time for previous operation to complete

  • Custom Validation Exceptions

    Problem: Validation rule or trigger blocks record updates during cart-to-order or order summary processing.

    Impact: Process fails with FIELD_CUSTOM_VALIDATION_EXCEPTION, interrupting checkout completion.

    Solution: Review and update validation rules and triggers to align with checkout and order creation flow.

  • ListPrice Mapping

    Problem: CartItem.SalesPrice maps to OrderItem.ListPrice by default, but you expect CartItem.ListPrice to map instead.

    Impact: Mapping appears incorrect based on expectations.

    Solution: Enable SalesPriceToListPriceMap org permission to map CartItem.ListPrice to OrderItem.ListPrice.

  • Missing CartValidationOutput Records

    Problem: Custom extensions (Tax, Inventory, Pricing, Promotions, Shipping) don't create CartValidationOutput records when failures occur.

    Impact: Checkout remains in inconsistent or blocked state, making it difficult to surface and handle errors.

    Solution: Make sure that all extensions create CartValidationOutput records upon failure.

  • Creating Checkout Session via Custom Apex

    Problem: Custom Apex creates CartCheckoutSession records while also using POST /checkouts API.

    Impact: POST /checkouts API doesn't expect existing checkout session, leading to conflicts or unexpected behavior.

    Solution: Use the POST /checkouts API exclusively to manage checkout session creation. Avoid custom implementations for out-of-the-box functionality.