Skip to main content

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
  • Cart corrections - Items removed due to stock or business rule changes

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
  • Smaller payload size than full checkout update

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:

  • 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
    }
  ]
}

Best practices​

Always suspend before updating

  • Call suspend() on the checkout iframe before making backend API calls to update the cart
  • Always call resume() afterward, even if the update fails
  • This prevents race conditions where the iframe and backend state become inconsistent

Handle API errors gracefully

  • Always resume the iframe after any update attempt (success or failure) to prevent a stuck checkout
  • For 423 (Resource_Locked) errors, implement retry logic with exponential backoff (e.g., wait 500ms, then 1s, then 2s)

Important limitations​

  • Cannot update completed purchases - Cart updates only work before purchase completion
  • Resource locking - Only one update at a time per checkout session (returns HTTP 423 if another update is in progress)
  • Purchase commitment - Once customer clicks "Complete Purchase", cart is locked and returns HTTP 900 error