---
id: cart-management
title: Handling Shopping Cart Changes
hide_title: true
description: "How to handle cart updates during an active checkout session"
---

import Ingress from "../../../src/components/ingress/ingress.react";

<Ingress title="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.
</Ingress>

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.

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    participant Walley

    User->>Frontend: Modify cart (add item, change quantity)
    Frontend->>Frontend: Suspend checkout iframe
    Note over Frontend: Shows spinner, disables inputs
    
    Frontend->>Backend: POST /update-cart
    Backend->>Walley: PUT /checkouts/{id}/cart
    Note over Backend,Walley: Update cart items via Walley API
    
    Walley-->>Backend: Success response
    Backend-->>Frontend: Cart updated
    
    Frontend->>Frontend: Resume checkout iframe
    Note over Frontend: Reloads checkout with updated cart
    
    Frontend->>User: Display updated cart
```

## 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](/docs/checkout/optional/updatecart) 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:**

```http
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](/docs/checkout/optional/updatecheckout) 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](/docs/checkout/initcheckout) it is an object with an `items` array, and on [Update Cart](/docs/checkout/optional/updatecart) the items sit directly in the request body. Check the shape for the endpoint you are calling.
:::

**Backend API call:**

```http
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`

## Related documentation

- [Update Cart API](/docs/checkout/optional/updatecart) - Detailed API reference for cart updates
- [Update Checkout API](/docs/checkout/optional/updatecheckout) - Update entire checkout state
- [Client-side API](/docs/checkout/optional/clientapi) - Suspend and resume functions
- [ValidateOrder Callback](/docs/checkout/optional/validateorder) - Validate cart before payment