Update line items on a checkout session

Add, change the quantity of, or remove line items. An item with an existing id and quantity: 0 is removed; an item with variant_id and no id is added as a new line item.

PUT/ucp/checkout-sessions/{id}

Authorization

AuthorizationOAuth2 access token · headerrequired

Bearer token obtained from the OAuth authorization server discovered at ucp.oauth.metadata_url in the profile response (GET /.well-known/ucp). Token enforcement may happen at a gateway layer in front of this API.

Path parameters

idstringrequired

Checkout session id, as returned in id / links.self from the create response.

Request body

requiredapplication/json

line_itemsobject[]required

Show properties

Array of object

idstring

variant_idinteger

quantityinteger

min 0

Responses

200

Updated checkout session

ucpUcpEnveloperequired

Protocol version and capability envelope included in every UCP response.

Show properties

versionstringrequired

capabilitiesobjectrequired

Show properties

checkoutstring

idstringrequired

statusstringrequired

Allowed:incompleteready_for_completerequires_escalation

currencystringrequired

line_itemsLineItem[]required

Show properties

Array of LineItem

idstringrequired

variant_idstringrequired

product_idstringrequired

namestringrequired

skustring

quantityintegerrequired

unit_priceintegerrequired

Minor units (e.g. cents)

totalintegerrequired

Minor units (e.g. cents)

totalsTotalsrequired

Show properties

subtotalintegerrequired

taxintegerrequired

shippingintegerrequired

discountintegerrequired

totalintegerrequired

buyerBuyer

Show properties

namestring

emailstring<email>

phonestring

linksCheckoutSessionLinksrequired

Show properties

selfstring<uri>required

continue_urlstring<uri>

Present once the session has moved to checkout — hosted web checkout to finish paying.

messagesMessage[]

Show properties

Array of Message

typestringrequired

Allowed:infoerrorwarning

codestringrequired

contentstringrequired

400

Malformed request body

ucpUcpEnveloperequired

Protocol version and capability envelope included in every UCP response.

Show properties

versionstringrequired

capabilitiesobjectrequired

Show properties

checkoutstring

messagesMessage[]required

Show properties

Array of Message

typestringrequired

Allowed:infoerrorwarning

codestringrequired

contentstringrequired

404

No checkout session exists with the given id

ucpUcpEnveloperequired

Protocol version and capability envelope included in every UCP response.

Show properties

versionstringrequired

capabilitiesobjectrequired

Show properties

checkoutstring

messagesMessage[]required

Show properties

Array of Message

typestringrequired

Allowed:infoerrorwarning

codestringrequired

contentstringrequired

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

OAuth2 access tokenRemember on this deviceInclude my values in samples

Parameters

idpath*Checkout session id, as returned in `id` / `links.self` from the create response.

Bodyapplication/json

Request body

Request

curl -X PUT '/ucp/checkout-sessions/string' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "line_items": [
    {
      "id": "string",
      "variant_id": 0,
      "quantity": 0
    }
  ]
}'

const response = await fetch("/ucp/checkout-sessions/string", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"line_items\": [\n    {\n      \"id\": \"string\",\n      \"variant_id\": 0,\n      \"quantity\": 0\n    }\n  ]\n}"
});

import requests

response = requests.put(
    "/ucp/checkout-sessions/string",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"line_items\": [\n    {\n      \"id\": \"string\",\n      \"variant_id\": 0,\n      \"quantity\": 0\n    }\n  ]\n}",
)

Response

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "checkout": "1.0"
    }
  },
  "id": "string",
  "status": "incomplete",
  "currency": "USD",
  "line_items": [
    {
      "id": "string",
      "variant_id": "string",
      "product_id": "string",
      "name": "string",
      "sku": "string",
      "quantity": 0,
      "unit_price": 0,
      "total": 0
    }
  ],
  "totals": {
    "subtotal": 0,
    "tax": 0,
    "shipping": 0,
    "discount": 0,
    "total": 0
  },
  "buyer": {
    "name": "string",
    "email": "user@example.com",
    "phone": "string"
  },
  "links": {
    "self": "http://example.com",
    "continue_url": "http://example.com"
  },
  "messages": [
    {
      "type": "info",
      "code": "string",
      "content": "string"
    }
  ]
}

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "checkout": "1.0"
    }
  },
  "messages": [
    {
      "type": "info",
      "code": "string",
      "content": "string"
    }
  ]
}

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "checkout": "1.0"
    }
  },
  "messages": [
    {
      "type": "info",
      "code": "string",
      "content": "string"
    }
  ]
}