How to handle shopping cart changes

During an active checkout session, customers may need to change their cart contents - adding items, adjusting quantities, removing products, or applying discounts. Walley Checkout provides APIs to handle these changes seamlessly while maintaining checkout state and customer information.

Cart changes must be synchronized with Walley to ensure accurate pricing, tax calculations, and payment processing. This guide explains when and how to update the cart during checkout.

Common scenarios requiring cart updates

• Quantity changes - Customer increases or decreases item quantities
• Add/remove items - Customer continues shopping and modifies cart
• Price updates - Promotions, discounts, or dynamic pricing changes
• Stock adjustments - Items become unavailable and must be removed
• Upsell/cross-sell - Additional products offered during checkout
• Gift card application - Customer applies gift cards after checkout starts
• Shipping cost changes - Delivery method selection affects cart total

Example flow

The typical flow for handling cart changes involves suspending the checkout, updating the cart via backend API, and resuming the checkout to reflect the changes.

Implementation approaches

There are two main approaches to updating the cart, depending on what needs to change:

Option 1: Update cart only

Use the Update Cart API when you only need to modify cart items without changing other checkout properties.

When to use:

• Only cart items or quantities change
• Price updates on existing items
• Adding or removing products
• Fastest option for cart-only changes

Backend API call:

PUT /checkouts/{checkout-id}/cart HTTP/1.1
Host: api.uat.walleydev.com
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...
Content-Type: application/json

{
  "items": [
    {
      "id": "10001",
      "description": "Product 1",
      "unitPrice": 100.0,
      "quantity": 2,
      "vat": 25.0
    },
    {
      "id": "10002",
      "description": "Product 2",
      "unitPrice": 50.0,
      "quantity": 1,
      "vat": 25.0
    }
  ]
}

Option 2: Update entire checkout

Use the Update Checkout API when you need to update multiple checkout properties simultaneously.

When to use:

• Cart items AND shipping properties change
• Cart items AND fees change together
• Updating reference or metadata along with cart
• Complex updates requiring multiple changes

Backend API call:

PUT /checkouts/{checkout-id} HTTP/1.1
Host: api.uat.walleydev.com
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...
Content-Type: application/json

{
  "cart": [
    {
      "id": "10001",
      "description": "Product 1",
      "unitPrice": 100.0,
      "quantity": 2,
      "vat": 25.0
    }
  ],
  "fees": {
    "shipping": {
      "id": "shipping001",
      "description": "Express Shipping",
      "unitPrice": 79.0,
      "vat": 25.0
    }
  },
  "shippingProperties": {
    "weight": 2.5,
    "height": 20
  }
}

Handling special cart scenarios

Empty cart

If all items are removed from the cart, the checkout cannot proceed. You should either:

1. Add a placeholder item - A service fee or minimum order item
2. Redirect customer - Return them to shop if cart is empty
3. Show error state - Prevent checkout completion

Price changes

When prices change significantly, inform the customer clearly.

Out of stock items

Remove unavailable items and notify the customer.

Integration with validation callbacks

When using ValidateOrder callbacks, you can validate the final cart state before payment. This ensures that the cart state is validated immediately before payment, catching any last-minute issues.

Best practices

Always suspend before updating

• Use suspend() before any backend cart update
• Always call resume() afterward, even if update fails
• This prevents race conditions and UI inconsistencies

Handle errors gracefully

• Always resume checkout on errors
• Show clear error messages to customers
• Log errors for debugging
• Provide fallback options (retry, contact support)

Validate cart state

• Check for empty carts before updates
• Validate item quantities and prices
• Verify stock availability before adding items
• Use ValidateOrder callback for final verification

Optimize performance

• Batch multiple changes into single update
• Cache cart state to minimize API calls
• Use debouncing for rapid quantity changes
• Show loading indicators during updates

Communicate changes clearly

• Show notifications when cart updates
• Highlight price differences
• Explain why items were removed
• Provide clear next steps

Consider timing

• Update cart as soon as changes occur
• Don't wait until payment attempt
• Validate before customer fills out form
• Use callbacks for final verification before payment

Important limitations

• Cannot update completed purchases - Cart updates only work before purchase completion
• Resource locking - Only one update at a time per checkout session
• Purchase commitment - Once customer clicks "Complete Purchase", cart is locked
• 10-second validation timeout - If using ValidateOrder, respond within 10 seconds

Error handling

Common errors when updating cart:

Error Code	Reason	Solution
400	Validation_Error	Check item properties (price, quantity, VAT are valid)
400	Duplicate_Articles	Ensure unique combination of id and description
423	Resource_Locked	Another update in progress - retry after brief delay
900	Purchase_Commitment_Found	Customer clicked Complete Purchase - cart is locked
900	Purchase_Completed	Purchase already finished - cannot modify

Related documentation

• Update Cart API - Detailed API reference for cart updates
• Update Checkout API - Update entire checkout state
• Client-side API - Suspend and resume functions
• ValidateOrder Callback - Validate cart before payment
• Gift Cards - Special cart item type example
• Inventory Validation - Stock validation strategies

Summary

Cart changes during checkout are common and must be handled carefully to maintain data consistency. Key takeaways:

• Suspend before updates - Always suspend checkout before cart modifications
• Choose right API - Use Update Cart for cart-only changes, Update Checkout for multiple properties
• Handle errors - Always resume checkout and show clear error messages
• Validate state - Use callbacks to validate final cart state before payment
• Communicate clearly - Keep customers informed about cart changes

By following these patterns, you can provide a smooth checkout experience even when cart contents need to change during the payment process.