---
title: "UCP: complete a checkout (charge and place the order)"
method: POST
path: "/api/ucp/checkout-sessions/{id}/complete"
tags: ["Agentic checkout (UCP)"]
---

# UCP: complete a checkout (charge and place the order)

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

## Request

- Base URL: `https://www.adadiamonds.com`
- URL: `https://www.adadiamonds.com/api/ucp/checkout-sessions/{id}/complete`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://www.adadiamonds.com/oauth/authorize`, token URL `https://www.adadiamonds.com/api/oauth/token`; client credentials, token URL `https://www.adadiamonds.com/api/oauth/token`, scopes: `cart:write`)

Accepts `payment.instruments[]` with a `PAYMENT_GATEWAY` credential (Google Pay token, Stripe gateway), a Stripe token, or a Shared Payment Token. Returns `status: completed` with `order`.

## Path parameters

- `id` string, required

## Headers

- `UCP-Agent` string, required
- `Idempotency-Key` string
- `Request-Id` string

## Request body

- UcpCompleteRequest
  - `payment` object, required
    - `instruments` UcpPaymentInstrument[], required
      - `id` string
      - `handler_id` string, required
      - `type` string, required
      - `selected` boolean
      - `billing_address` UcpPostalAddress
        - `type` string
        - `id` string
        - `first_name` string
        - `last_name` string
        - `full_name` string
        - `street_address` string
        - `extended_address` string
        - `address_locality` string
        - `address_region` string
        - `postal_code` string
        - `address_country` string
        - `phone_number` string
      - `credential` object, required
        - `type` 'PAYMENT_GATEWAY' | 'stripe_payment_token' | 'spt', required
        - `token` string, required
  - `buyer` UcpBuyer
    - `first_name` string
    - `last_name` string
    - `email` string, email
    - `phone_number` string
  - `signals` object

## Response `200`

Checkout resource inside the `ucp` envelope. Business outcomes, including not-found and cannot-cancel, are HTTP 200 with `messages[]`.

- UcpCheckout
  - `ucp` UcpEnvelope, required
    - `version` string, required
    - `status` 'success' | 'error', required
    - `capabilities` object
    - `payment_handlers` object
  - `id` string, required
  - `status` 'incomplete' | 'requires_escalation' | 'ready_for_complete' | 'complete_in_progress' | 'completed' | 'canceled', required
  - `currency` 'USD', required
  - `expires_at` string, date-time
  - `continue_url` string, uri
  - `buyer` UcpBuyer
    - `first_name` string
    - `last_name` string
    - `email` string, email
    - `phone_number` string
  - `line_items` UcpLineItem[], required
    - `id` string, required
    - `item` object, required
      - `id` string, required
      - `title` string, required
      - `price` integer, required: Unit price. Integer minor units (cents).
      - `image_url` string, uri
    - `quantity` integer, required
    - `totals` UcpTotal[], required
      - `type` 'subtotal' | 'discount' | 'fulfillment' | 'tax' | 'fee' | 'total', required
      - `amount` integer, required: Amount. Integer minor units (cents).
  - `totals` UcpTotal[], required
    - `type` 'subtotal' | 'discount' | 'fulfillment' | 'tax' | 'fee' | 'total', required
    - `amount` integer, required: Amount. Integer minor units (cents).
  - `messages` UcpMessage[]
    - `type` 'error' | 'warning' | 'info', required
    - `code` string: missing, out_of_stock, item_unavailable, payment_failed, eligibility_invalid, not_found, unauthorized, conflict, expired, idempotency_conflict, signature_invalid
    - `content` string, required
    - `content_type` 'plain' | 'markdown'
    - `severity` 'recoverable' | 'requires_buyer_input' | 'requires_buyer_review' | 'unrecoverable'
    - `path` string: RFC 9535 JSONPath
  - `links` object[], required
    - `type` 'privacy_policy' | 'terms_of_service' | 'refund_policy' | 'shipping_policy' | 'faq', required
    - `url` string, uri, required
  - `fulfillment` object
  - `payment` object
  - `order` UcpOrder
    - `id` string, required
    - `label` string
    - `permalink_url` string, uri, required

## Other responses

- `400`: Malformed JSON.
- `401`: Missing or invalid bearer token, or request signature failed verification.
- `403`: Credential lacks the cart:write scope (production only).
- `409`: Idempotency-Key reused with a different body, or still in flight.
- `503`: Checkout storage unavailable.

---

[API](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api.md) · [All operations](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api/revisions/2b2ed3201815?raw)