Create a checkout session

Creates a new checkout session (cart), optionally pre-populated with line items.

POST/ucp/checkout-sessions

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.

Request body

application/json

line_itemsobject[]

Show properties

Array of object

variant_idintegerrequired

quantityintegerrequired

min 1

Responses

201

Checkout session created

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

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

OAuth2 access tokenRemember on this deviceInclude my values in samples

Bodyapplication/json

Request body

Request

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

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

import requests

response = requests.post(
    "/ucp/checkout-sessions",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"line_items\": [\n    {\n      \"variant_id\": 0,\n      \"quantity\": 1\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"
    }
  ]
}