Complete a checkout session

Attempts to complete the session. This storefront always requires a human-facing payment step, so a successful call returns status: requires_escalation with links.continue_url pointing to the hosted web checkout where the buyer must finish paying — it does not finalize the order by itself.

POST/ucp/checkout-sessions/{id}/complete

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.

Responses

200

Session moved to checkout; continue at links.continue_url to finish paying

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

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

422

Session is not in a state that can be completed, or no web checkout is available

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.

Request

curl -X POST '/ucp/checkout-sessions/string/complete' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/json'

const response = await fetch("/ucp/checkout-sessions/string/complete", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json"
  }
});

import requests

response = requests.post(
    "/ucp/checkout-sessions/string/complete",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Accept": "application/json"
    },
)

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"
    }
  ]
}