Skip to main content

Handling shopping cart changes

Customers change their cart during an active checkout session by adding items, adjusting quantities, removing products or applying discounts. Walley Checkout gives you APIs to apply those changes while the checkout keeps its state and the customer information already collected.

Synchronize every cart change with Walley so that pricing, tax calculations and payment processing stay accurate. 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
note

On this endpoint cart is an array of items. On Initialize Checkout it is an object with an items array, and on Update Cart the items sit directly in the request body. Check the shape for the endpoint you are calling.

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 the customer clicks "Complete Purchase", Walley locks the cart and further updates return code 900 with the reason Purchase_Commitment_Found