Ada Diamonds Agentic checkout (UCP) API

openapi: 3.2.0
info:
  title: Ada Diamonds Agent Agentic checkout (UCP) API
  version: 1.1.0
  summary: Read Ada Diamonds' lab grown diamond inventory, engagement ring settings, fine jewelry, and buying guides — and request a jeweler consultation.
  description: 'The Ada Diamonds Agent API gives AI agents and applications structured access to Ada Diamonds'' live catalog and published content.


    **Catalog and content endpoints require no credential.** An agent answering a shopper''s question should not need an onboarding step first. Credentials exist to raise rate limits and to reach the endpoints that touch a specific customer''s data. The API roots (`/api`, `/api/v1`) are the one read that challenges anonymous callers, with a `WWW-Authenticate: Bearer` header that points at the OAuth metadata.


    **Pricing model.** An engagement ring is a setting plus a loose diamond, priced separately. `priceFrom` on a setting excludes the center stone. All prices are US dollars.


    **Getting a credential.** `POST /api/v1/keys` issues a working API key immediately, no account required. For customer-specific access, register an OAuth client at `/api/oauth/register` and use the authorization code flow with PKCE.


    **Sandbox.** Request `{"env":"sandbox"}` when creating a key. Sandbox credentials read the real catalog and accept writes without creating anything.


    **Batching.** `POST /api/v1/batch` runs up to 20 public reads in one request and returns each sub-response with its own status. Use it to assemble a quote (a setting plus several stones) in a single round trip. A batch counts as one request against the rate limit.


    **Long-running operations.** Whole-catalog exports are asynchronous: `POST /api/v1/exports` answers 202 with a `Location` header for the job. Poll `GET /api/v1/jobs/{id}` (honouring `Retry-After`) until `status` is `succeeded`, then download `result_url`. Exports complete within seconds and job ids stay valid for 24 hours. Operations marked `x-async: true` follow this pattern.


    **MCP.** The same catalog is available as an MCP server at https://www.adadiamonds.com/mcp (streamable HTTP); the server card at https://www.adadiamonds.com/.well-known/mcp/server-card.json lists its tools.'
  termsOfService: https://www.adadiamonds.com/terms
  contact:
    name: Ada Diamonds developer support
    email: it@adadiamonds.com
    url: https://www.adadiamonds.com/developers
  license:
    name: Ada Diamonds API Terms
    url: https://www.adadiamonds.com/terms
servers:
- url: https://www.adadiamonds.com
  description: Production
- url: https://www.adadiamonds.com/sandbox
  description: 'Sandbox: every path below, mounted under /sandbox. Credential-less requests are treated as the public sandbox key; reads return the live catalog, writes are acknowledged and create nothing. Described at /sandbox.'
security:
- {}
- apiKey: []
- oauth2:
  - catalog:read
  - content:read
tags:
- name: Agentic checkout (UCP)
paths:
  /api/ucp/checkout-sessions:
    post:
      operationId: ucpCreateCheckout
      summary: 'UCP: create a checkout'
      description: REST binding of `dev.ucp.shopping.checkout` (2026-04-08). Item ids are the same as the ACP feed. Every response carries the `ucp` negotiation envelope.
      tags:
      - Agentic checkout (UCP)
      security:
      - bearerAuth: []
      - oauth2:
        - cart:write
      parameters:
      - in: header
        name: UCP-Agent
        required: true
        description: 'Platform profile, RFC 8941 dictionary syntax: `profile="https://platform.example/.well-known/ucp"`.'
        schema:
          type: string
      - in: header
        name: Idempotency-Key
        required: false
        description: Optional but recommended on state-changing requests; a reused key with a different body is rejected with 409.
        schema:
          type: string
          maxLength: 255
      - in: header
        name: Request-Id
        required: false
        description: Trace id; echoed back when provided.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UcpCheckoutRequest'
      responses:
        '201':
          description: Checkout resource inside the `ucp` envelope. Business outcomes, including not-found and cannot-cancel, are HTTP 200 with `messages[]`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpCheckout'
        '400':
          description: Malformed JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '401':
          description: Missing or invalid bearer token, or request signature failed verification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '403':
          description: Credential lacks the cart:write scope (production only).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '409':
          description: Idempotency-Key reused with a different body, or still in flight.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '503':
          description: Checkout storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
  /api/ucp/checkout-sessions/{id}:
    get:
      operationId: ucpGetCheckout
      summary: 'UCP: get a checkout'
      description: 'Return the latest state of a checkout session inside the `ucp` negotiation envelope. Status uses the UCP vocabulary (`incomplete`, `ready_for_complete`, `complete_in_progress`, `completed`, `canceled`) and amounts are integer cents in USD. An unknown id, or one owned by another credential, is a business outcome: HTTP 200 with `ucp.status: error` and a `not_found` message. Requires a bearer token; the sandbox key returns sandbox sessions.'
      tags:
      - Agentic checkout (UCP)
      security:
      - bearerAuth: []
      - oauth2:
        - cart:write
      parameters:
      - in: path
        name: id
        required: true
        description: Checkout session id returned by create.
        schema:
          type: string
      - in: header
        name: UCP-Agent
        required: true
        description: 'Platform profile, RFC 8941 dictionary syntax: `profile="https://platform.example/.well-known/ucp"`.'
        schema:
          type: string
      - in: header
        name: Request-Id
        required: false
        description: Trace id; echoed back when provided.
        schema:
          type: string
      responses:
        '200':
          description: Checkout resource inside the `ucp` envelope. Business outcomes, including not-found and cannot-cancel, are HTTP 200 with `messages[]`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpCheckout'
        '400':
          description: Malformed JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '401':
          description: Missing or invalid bearer token, or request signature failed verification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '403':
          description: Credential lacks the cart:write scope (production only).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '409':
          description: Idempotency-Key reused with a different body, or still in flight.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '503':
          description: Checkout storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
    put:
      operationId: ucpUpdateCheckout
      summary: 'UCP: update a checkout (full replacement)'
      description: 'Replace the checkout: `line_items` is required and replaces the current lines; `buyer` and `fulfillment` (schema.org destination, selected option) replace their sections when present and are kept when omitted. Totals, tax, and the single fulfillment option are recomputed and the session moves to `ready_for_complete` once buyer email, a full shipping address, and a fitting center diamond for any setting are present. Not permitted while `complete_in_progress`. An optional Idempotency-Key is honoured (same body replays, different body 409).'
      tags:
      - Agentic checkout (UCP)
      security:
      - bearerAuth: []
      - oauth2:
        - cart:write
      parameters:
      - in: path
        name: id
        required: true
        description: Checkout session id returned by create.
        schema:
          type: string
      - in: header
        name: UCP-Agent
        required: true
        description: 'Platform profile, RFC 8941 dictionary syntax: `profile="https://platform.example/.well-known/ucp"`.'
        schema:
          type: string
      - in: header
        name: Idempotency-Key
        required: false
        description: Optional but recommended on state-changing requests; a reused key with a different body is rejected with 409.
        schema:
          type: string
          maxLength: 255
      - in: header
        name: Request-Id
        required: false
        description: Trace id; echoed back when provided.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UcpCheckoutRequest'
      responses:
        '200':
          description: Checkout resource inside the `ucp` envelope. Business outcomes, including not-found and cannot-cancel, are HTTP 200 with `messages[]`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpCheckout'
        '400':
          description: Malformed JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '401':
          description: Missing or invalid bearer token, or request signature failed verification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '403':
          description: Credential lacks the cart:write scope (production only).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '409':
          description: Idempotency-Key reused with a different body, or still in flight.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '503':
          description: Checkout storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
  /api/ucp/checkout-sessions/{id}/complete:
    post:
      operationId: ucpCompleteCheckout
      summary: 'UCP: complete a checkout (charge and place the order)'
      description: '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`.'
      tags:
      - Agentic checkout (UCP)
      security:
      - bearerAuth: []
      - oauth2:
        - cart:write
      parameters:
      - in: path
        name: id
        required: true
        description: Checkout session id returned by create.
        schema:
          type: string
      - in: header
        name: UCP-Agent
        required: true
        description: 'Platform profile, RFC 8941 dictionary syntax: `profile="https://platform.example/.well-known/ucp"`.'
        schema:
          type: string
      - in: header
        name: Idempotency-Key
        required: false
        description: Optional but recommended on state-changing requests; a reused key with a different body is rejected with 409.
        schema:
          type: string
          maxLength: 255
      - in: header
        name: Request-Id
        required: false
        description: Trace id; echoed back when provided.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UcpCompleteRequest'
      responses:
        '200':
          description: Checkout resource inside the `ucp` envelope. Business outcomes, including not-found and cannot-cancel, are HTTP 200 with `messages[]`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpCheckout'
        '400':
          description: Malformed JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '401':
          description: Missing or invalid bearer token, or request signature failed verification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '403':
          description: Credential lacks the cart:write scope (production only).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '409':
          description: Idempotency-Key reused with a different body, or still in flight.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '503':
          description: Checkout storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
  /api/ucp/checkout-sessions/{id}/cancel:
    post:
      operationId: ucpCancelCheckout
      summary: 'UCP: cancel a checkout'
      description: 'Cancel a checkout that is not yet completed; the response is the checkout with `status: canceled`. A checkout that is already `completed` or `canceled` is returned unchanged with an error message (`conflict`) and HTTP 200, per the UCP rule that business outcomes are not HTTP errors. Requires a bearer token and the `UCP-Agent` header; an Idempotency-Key is optional. Sandbox and production sessions behave the same.'
      tags:
      - Agentic checkout (UCP)
      security:
      - bearerAuth: []
      - oauth2:
        - cart:write
      parameters:
      - in: path
        name: id
        required: true
        description: Checkout session id returned by create.
        schema:
          type: string
      - in: header
        name: UCP-Agent
        required: true
        description: 'Platform profile, RFC 8941 dictionary syntax: `profile="https://platform.example/.well-known/ucp"`.'
        schema:
          type: string
      - in: header
        name: Idempotency-Key
        required: false
        description: Optional but recommended on state-changing requests; a reused key with a different body is rejected with 409.
        schema:
          type: string
          maxLength: 255
      - in: header
        name: Request-Id
        required: false
        description: Trace id; echoed back when provided.
        schema:
          type: string
      responses:
        '200':
          description: Checkout resource inside the `ucp` envelope. Business outcomes, including not-found and cannot-cancel, are HTTP 200 with `messages[]`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpCheckout'
        '400':
          description: Malformed JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '401':
          description: Missing or invalid bearer token, or request signature failed verification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '403':
          description: Credential lacks the cart:write scope (production only).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '409':
          description: Idempotency-Key reused with a different body, or still in flight.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
        '503':
          description: Checkout storage unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpErrorResponse'
components:
  schemas:
    UcpTotal:
      type: object
      required:
      - type
      - amount
      properties:
        type:
          type: string
          enum:
          - subtotal
          - discount
          - fulfillment
          - tax
          - fee
          - total
        amount:
          type: integer
          description: Amount. Integer minor units (cents).
    UcpPaymentInstrument:
      type: object
      required:
      - handler_id
      - type
      - credential
      properties:
        id:
          type: string
        handler_id:
          type: string
          example: gpay_ada_stripe
        type:
          type: string
          example: CARD
        selected:
          type: boolean
        billing_address:
          $ref: '#/components/schemas/UcpPostalAddress'
        credential:
          type: object
          required:
          - type
          - token
          properties:
            type:
              type: string
              enum:
              - PAYMENT_GATEWAY
              - stripe_payment_token
              - spt
            token:
              type: string
    UcpLineItem:
      type: object
      required:
      - id
      - item
      - quantity
      - totals
      properties:
        id:
          type: string
        item:
          type: object
          required:
          - id
          - title
          - price
          properties:
            id:
              type: string
            title:
              type: string
            price:
              type: integer
              description: Unit price. Integer minor units (cents).
            image_url:
              type: string
              format: uri
        quantity:
          type: integer
        totals:
          type: array
          items:
            $ref: '#/components/schemas/UcpTotal'
    UcpEnvelope:
      type: object
      required:
      - version
      - status
      properties:
        version:
          type: string
          example: '2026-04-08'
        status:
          type: string
          enum:
          - success
          - error
        capabilities:
          type: object
        payment_handlers:
          type: object
    UcpPostalAddress:
      type: object
      properties:
        type:
          type: string
          example: shipping_address
        id:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        full_name:
          type: string
        street_address:
          type: string
        extended_address:
          type: string
        address_locality:
          type: string
        address_region:
          type: string
        postal_code:
          type: string
        address_country:
          type: string
        phone_number:
          type: string
    UcpCheckoutRequest:
      type: object
      required:
      - line_items
      properties:
        line_items:
          type: array
          minItems: 1
          items:
            type: object
            required:
            - item
            properties:
              item:
                type: object
                required:
                - id
                properties:
                  id:
                    type: string
                    example: setting:the-oval-solitaire
              quantity:
                type: integer
                minimum: 1
                default: 1
        buyer:
          $ref: '#/components/schemas/UcpBuyer'
        context:
          type: object
          properties:
            language:
              type: string
        fulfillment:
          type: object
          properties:
            methods:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                    - shipping
                  selected_destination_id:
                    type: string
                  destinations:
                    type: array
                    items:
                      $ref: '#/components/schemas/UcpPostalAddress'
                  groups:
                    type: array
                    items:
                      type: object
                      properties:
                        selected_option_id:
                          type: string
    UcpBuyer:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        phone_number:
          type: string
    UcpCompleteRequest:
      type: object
      required:
      - payment
      properties:
        payment:
          type: object
          required:
          - instruments
          properties:
            instruments:
              type: array
              items:
                $ref: '#/components/schemas/UcpPaymentInstrument'
        buyer:
          $ref: '#/components/schemas/UcpBuyer'
        signals:
          type: object
    UcpErrorResponse:
      type: object
      required:
      - ucp
      - messages
      properties:
        ucp:
          $ref: '#/components/schemas/UcpEnvelope'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/UcpMessage'
        continue_url:
          type: string
          format: uri
    UcpOrder:
      type: object
      required:
      - id
      - permalink_url
      properties:
        id:
          type: string
        label:
          type: string
          example: '#AD-2026-123456'
        permalink_url:
          type: string
          format: uri
    UcpCheckout:
      type: object
      required:
      - ucp
      - id
      - line_items
      - status
      - currency
      - totals
      - links
      properties:
        ucp:
          $ref: '#/components/schemas/UcpEnvelope'
        id:
          type: string
          example: ucp_1f6a5b2e-4c3d-4e5f-8a9b-0c1d2e3f4a5b
        status:
          type: string
          enum:
          - incomplete
          - requires_escalation
          - ready_for_complete
          - complete_in_progress
          - completed
          - canceled
        currency:
          type: string
          enum:
          - USD
        expires_at:
          type: string
          format: date-time
        continue_url:
          type: string
          format: uri
        buyer:
          $ref: '#/components/schemas/UcpBuyer'
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/UcpLineItem'
        totals:
          type: array
          items:
            $ref: '#/components/schemas/UcpTotal'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/UcpMessage'
        links:
          type: array
          items:
            type: object
            required:
            - type
            - url
            properties:
              type:
                type: string
                enum:
                - privacy_policy
                - terms_of_service
                - refund_policy
                - shipping_policy
                - faq
              url:
                type: string
                format: uri
        fulfillment:
          type: object
        payment:
          type: object
        order:
          $ref: '#/components/schemas/UcpOrder'
    UcpMessage:
      type: object
      required:
      - type
      - content
      properties:
        type:
          type: string
          enum:
          - error
          - warning
          - info
        code:
          type: string
          description: missing, out_of_stock, item_unavailable, payment_failed, eligibility_invalid, not_found, unauthorized, conflict, expired, idempotency_conflict, signature_invalid
        content:
          type: string
        content_type:
          type: string
          enum:
          - plain
          - markdown
        severity:
          type: string
          enum:
          - recoverable
          - requires_buyer_input
          - requires_buyer_review
          - unrecoverable
        path:
          type: string
          description: RFC 9535 JSONPath
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'An Ada API key or OAuth access token sent as `Authorization: Bearer <credential>`. Agentic checkout requires it; sandbox keys (ada_test_*) complete without charging.'
    apiKey:
      type: apiKey
      in: header
      name: X-Ada-Api-Key
      description: 'Self-serve key from POST /api/v1/keys. Also accepted as `Authorization: Bearer <key>`. Public read scopes only.'
    oauth2:
      type: oauth2
      description: OAuth 2.1. PKCE is mandatory on the authorization code flow. Clients may self-register at /api/oauth/register (RFC 7591).
      flows:
        authorizationCode:
          authorizationUrl: https://www.adadiamonds.com/oauth/authorize
          tokenUrl: https://www.adadiamonds.com/api/oauth/token
          refreshUrl: https://www.adadiamonds.com/api/oauth/token
          scopes:
            catalog:read: Read the public product catalog — diamonds, engagement rings, and fine jewelry, with prices and specifications.
            content:read: Read published editorial content — knowledge base articles, buying guides, and showroom information.
            profile:read: Read the signed-in customer's account profile (name, email, saved preferences).
            orders:read: Read the signed-in customer's order history and order status.
            cart:write: Create and modify a shopping cart on the signed-in customer's behalf.
            appointments:write: Request a consultation or showroom appointment on the signed-in customer's behalf.
        clientCredentials:
          tokenUrl: https://www.adadiamonds.com/api/oauth/token
          scopes:
            catalog:read: Read the public product catalog — diamonds, engagement rings, and fine jewelry, with prices and specifications.
            content:read: Read published editorial content — knowledge base articles, buying guides, and showroom information.
externalDocs:
  description: Ada Diamonds developer documentation
  url: https://www.adadiamonds.com/developers