# 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.