---
id: updatecheckout
title: Update checkout
hide_title: true
description: "Update checkout call for Walley Checkout API"
---

import Link from "@docusaurus/Link";
import Ingress from "../../../src/components/ingress/ingress.react";

<Ingress title="Update checkout">
  The Update checkout request will replace the entire checkout state. If you
  update the Checkout while the Checkout is visible, use the
  <a href="/docs/checkout/optional/clientapi">Checkout Client API's</a> to
  invoke <code>suspend</code> before your operation and <code>resume</code>
  afterward. You can also update the objects individually:
  [cart](/docs/checkout/optional/updatecart), <Link to="/reference#tag/checkout/PUT/checkouts/{checkoutId}/shippingproperties" data-noBrokenLinkCheck>shippingProperties</Link>, [fees](/docs/checkout/optional/updatefees), [shipping](/docs/checkout/delivery/ingrid?tab=update#extending-regular-walley-api-requests), [reference](/docs/checkout/optional/updateorderreference), [metadata](/docs/checkout/optional/updatemetadata)
</Ingress>

:::info Important
This operation is only available while the purchase is still in progress.
:::

While the checkout is suspended, the checkout can be updated by calling the Checkout API from your backend:

```http
PUT /checkouts/{checkoutId} HTTP/1.1
```

:::note[API Reference]
See **<Link to="/reference#tag/checkout/PUT/checkouts/{checkoutId}" data-noBrokenLinkCheck>Update checkout</Link>** for the request schema, property descriptions, examples and error reasons.
:::

## Replace semantics

:::info Important
The Update checkout PUT request will replace the checkout state. Providing `null` to (or omitting) the optional properties `shippingProperties`, `shipping`, `fees` or `metadata` will remove the existing value.

`reference`, `settlementReference` and `upsell` are the exceptions. Omit them, or send `null`, and the existing values stay.
:::

Only `cart` is required for a Checkout session that results in an order. `shippingProperties`, `shipping`, `fees`, `reference`, `settlementReference`, [`upsell`](/docs/checkout/optional/upsell) and `metadata` are all optional.

## Cart

:::note Cart Validation
The cart cannot consist entirely of items with negative `unitPrice` values. At least one item in the cart must have a non-negative unit price.
:::

The item constraints are the same as for the dedicated endpoint. See [Update cart](/docs/checkout/optional/updatecart#cart-items) for gift cards, strong identification and age limits.

## Fees

:::info
If the [Delivery Module](/docs/checkout/delivery/introduction-delivery-module) is used, the customer selects delivery method inside Walley Checkout and the `fees.shipping` object is obsolete.
:::

To set the shipping fee, add a `shipping` object to the fees object of the request. The `shipping` object can be `null` to remove the shipping fee for the current Checkout. Keep the combination of `id` and `description` unique within the Checkout session, cart articles included. That keeps every line distinct on the invoice and the receipt. Walley trims leading and trailing white-space from both values.

## Shipping and shipping properties

`shippingProperties` replaces any existing value. It consists of key-value pairs that will set shipping properties. Each key must be a string but the value can be string, boolean or number.

See [Extending regular Walley API requests](/docs/checkout/delivery/ingrid?tab=update#extending-regular-walley-api-requests) to learn more about how to update checkout when using Ingrid.

## References and metadata

`reference` is a reference to the order, such as an order ID. It is not shown to the customer, but it can be correlated with the PurchaseIdentifier that the customer does see.

Set `settlementReference` if you would like to group your settlement reports based on this value. It requires Settlement Settings to be set up on the Store ID by Merchant Services. See [Init Checkout Features](/docs/checkout/optional/init-checkout-features) for details.

`metadata` replaces any existing metadata. Each key in the object must be a string but the value can be any valid JSON value.

:::info
This endpoint cannot be used to update the reference after a purchase. Use [Update order reference](/docs/checkout/optional/updateorderreference) once the purchase is completed.
:::

## Error responses

The error reasons this endpoint can return are listed per status code in the <Link to="/reference#tag/checkout/PUT/checkouts/{checkoutId}" data-noBrokenLinkCheck>API Reference</Link>. The [Error codes](/docs/checkout/error-codes) page explains the HTTP status codes used across the Checkout API.