> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnicommerce.sg/llms.txt
> Use this file to discover all available pages before exploring further.

# Update UCP Checkout Session

> Update UCP cart, buyer, fulfillment, or payment rail fields. Provided fields are applied to the native checkout session and inventory reservations are refreshed when line items change. Requires `UCP-Agent` and OAuth `checkout:write`.



## OpenAPI

````yaml /openapi.json patch /ucp/v1/checkout-sessions/{sessionId}
openapi: 3.1.0
info:
  title: OmniCommerce API
  version: 1.0.0
  license:
    name: Proprietary
    url: https://omnicommerce.sg/terms
  description: >-
    OmniCommerce API surface for agents and developer integrations. Includes
    public endpoints (merchant discovery, product search, compare, catalog, ACO
    retrieval) and authenticated endpoints (product management via API key
    Bearer tokens).
servers:
  - url: https://omnicommerce.sg
    description: Production
  - url: http://localhost:3000
    description: Local development
security: []
tags:
  - name: agentic-checkout
    description: Merchant-fulfilled agentic checkout
    x-group: Agentic Checkout
  - name: commerce
    description: Root commerce discovery
    x-group: Commerce
  - name: developer-platform
    description: Authenticated developer platform APIs
    x-group: Developer Platform
  - name: looks
    description: AI-styled product looks
    x-group: Looks
  - name: oauth
    description: OAuth token endpoints
    x-group: OAuth
  - name: orders
    description: Workspace and agentic orders
    x-group: Orders
  - name: organizations
    description: Organization management
    x-group: Organizations
  - name: price-books
    description: Marketplace list-price markup rules
    x-group: Price Books
  - name: products
    description: Product CRUD, bulk import, and publish
    x-group: Products
  - name: promotions
    description: Central promotions and marketplace sync
    x-group: Promotions
  - name: public-agent
    description: Public agent discovery and catalog APIs
    x-group: Public Agent
  - name: settlements
    description: settlements
    x-group: Settlements
  - name: ucp
    description: Universal Commerce Protocol
    x-group: UCP
paths:
  /ucp/v1/checkout-sessions/{sessionId}:
    patch:
      tags:
        - ucp
      summary: Update UCP Checkout Session
      description: >-
        Update UCP cart, buyer, fulfillment, or payment rail fields. Provided
        fields are applied to the native checkout session and inventory
        reservations are refreshed when line items change. Requires `UCP-Agent`
        and OAuth `checkout:write`.
      operationId: patch_ucp_v1_checkout_sessions_by_sessionid
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
        - name: UCP-Agent
          in: header
          required: true
          description: UCP agent identity, for example `agent.example/1.0`.
          schema:
            type: string
            maxLength: 240
        - name: organizationId
          in: query
          required: false
          description: >-
            Optional organization scope for session-authenticated calls. OAuth
            client credentials resolve the organization from the token.
          schema:
            type: string
            maxLength: 120
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              properties:
                line_items:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: object
                    additionalProperties: true
                    required:
                      - item
                      - quantity
                    properties:
                      item:
                        type: object
                        additionalProperties: true
                        required:
                          - id
                        properties:
                          id:
                            type: string
                            description: OmniCommerce product UUID.
                            maxLength: 160
                          title:
                            type: string
                          price:
                            type: integer
                          image_url:
                            type: string
                      quantity:
                        type: integer
                        minimum: 1
                        maximum: 999
                buyer:
                  type: object
                  additionalProperties: true
                fulfillment:
                  type: object
                  additionalProperties: true
                payment:
                  type: object
                  additionalProperties: true
                payment_rail:
                  type: string
                  enum:
                    - acp_stripe
                    - x402
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: UCP checkout session updated.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                required:
                  - ucp
                  - id
                  - line_items
                  - status
                  - currency
                  - totals
                properties:
                  ucp:
                    type: object
                    additionalProperties: true
                  id:
                    type: string
                  line_items:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                      required:
                        - item
                        - quantity
                      properties:
                        item:
                          type: object
                          additionalProperties: true
                          required:
                            - id
                          properties:
                            id:
                              type: string
                              description: OmniCommerce product UUID.
                              maxLength: 160
                            title:
                              type: string
                            price:
                              type: integer
                            image_url:
                              type: string
                        quantity:
                          type: integer
                          minimum: 1
                          maximum: 999
                  buyer:
                    type: object
                    additionalProperties: true
                  fulfillment:
                    type: object
                    additionalProperties: true
                  status:
                    type: string
                    enum:
                      - ready_for_complete
                      - completed
                      - canceled
                  currency:
                    type: string
                  totals:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  payment:
                    type: object
                    additionalProperties: true
                  order:
                    type: object
                    additionalProperties: true
                  settlement:
                    type: object
                    additionalProperties: true
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden or checkout not enabled
        '404':
          description: Checkout session not found
        '409':
          description: Terminal session or insufficient inventory
        '500':
          description: Internal Server Error
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Bearer API key for server-to-server access. Session auth is also
        supported in first-party UI flows.

````