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

# Create Agent Checkout

> Start an agent checkout that drives a browser through a merchant checkout to purchase a product.

**API scope required**: `agent-checkouts.create`



## OpenAPI

````yaml post /unstable/agent-checkouts
openapi: 3.0.3
info:
  title: Crossmint Agent Checkouts API
  version: unstable
  description: >-
    Drive a real, automated browser session through any merchant's checkout on
    behalf of a signed-in user.


    You hand the API a product URL, an optional natural-language instruction,
    and a hard maximum cost. Crossmint runs a browser through the merchant's
    checkout pages, pausing for *user actions* (shipping, payment, anything only
    a human can answer) which you respond to with values that satisfy a supplied
    JSON Schema. There are no webhooks in v1 — poll the checkout until it
    reaches a terminal state.


    ## Base URL


    `https://www.crossmint.com/api` (production) ·
    `https://staging.crossmint.com/api` (staging)


    ## Authentication


    Every request requires **two** credentials:


    - `X-API-KEY` — a client-side API key (`ck_...`) with the
    `agent-checkouts.*` scopes.

    - `Authorization: Bearer <jwt>` — a JWT identifying the end user, issued by
    an external auth provider your project trusts. Without it the API returns
    `401`.


    <Note>This API lives under the `unstable` namespace. The schema may change —
    pin and re-test on upgrades.</Note>
servers:
  - url: https://www.crossmint.com/api
    description: Production
  - url: https://staging.crossmint.com/api
    description: Staging
security:
  - ApiKeyAuth: []
    BearerAuth: []
tags:
  - name: Agent Checkouts
    description: Create, poll, respond to, and cancel browser-driven checkouts.
  - name: Buyer Profiles
    description: >-
      Subject-scoped buyer identity and shipping address the agent can prefill
      during a checkout run. Payment data is never stored.
paths:
  /unstable/agent-checkouts:
    post:
      tags:
        - Agent Checkouts
      summary: Create Agent Checkout
      description: >-
        Starts an agent checkout that drives a browser through a merchant
        checkout to purchase a product. Returns the initial checkout view with
        `status: "queued"`. Save the returned `id` — it is both the checkout id
        and the id you poll, respond to, and cancel.


        **API scope required**: `agent-checkouts.create`
      operationId: createAgenticCheckout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgenticCheckoutRequest'
            examples:
              Direct URL with instruction:
                summary: Buy a specific variant under a spending cap
                value:
                  target:
                    kind: direct_url
                    url: https://merchant.example/products/classic-tee
                    request: buy the medium in black
                  constraints:
                    maxCost:
                      amount: '100.00'
                      currency: USD
                  metadata:
                    orderRef: order_8f2c
      responses:
        '201':
          description: The agent checkout has been initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgenticCheckout'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    CreateAgenticCheckoutRequest:
      type: object
      required:
        - target
        - constraints
      properties:
        target:
          $ref: '#/components/schemas/PurchaseTarget'
        packId:
          type: string
          format: uuid
          description: >-
            Optional legacy field: the id of a pack that guides the agent
            through this merchant's checkout. A checkout targets one merchant,
            so at most one pack applies. The applied pack is echoed back on the
            checkout view's `pack` field.
        buyerProfileId:
          type: string
          format: uuid
          description: >-
            Optional id of a saved buyer profile whose name, contact, and
            shipping the agent prefills instead of asking.
        constraints:
          $ref: '#/components/schemas/PurchaseConstraints'
        metadata:
          $ref: '#/components/schemas/CheckoutMetadata'
    AgenticCheckout:
      type: object
      description: The full checkout view, returned by create, get, and cancel.
      required:
        - id
        - status
        - target
        - constraints
        - progressItems
        - browser
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: The checkout id.
        status:
          $ref: '#/components/schemas/CheckoutStatus'
        target:
          $ref: '#/components/schemas/PurchaseTarget'
        pack:
          $ref: '#/components/schemas/IntentPackUsage'
        constraints:
          $ref: '#/components/schemas/PurchaseConstraints'
        pendingUserAction:
          $ref: '#/components/schemas/PendingUserAction'
        receipt:
          $ref: '#/components/schemas/Receipt'
        failure:
          $ref: '#/components/schemas/Failure'
        progressItems:
          type: array
          items:
            $ref: '#/components/schemas/ProgressItem'
        browser:
          $ref: '#/components/schemas/Browser'
        metadata:
          $ref: '#/components/schemas/CheckoutMetadata'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PurchaseTarget:
      type: object
      required:
        - kind
        - url
      properties:
        kind:
          type: string
          enum:
            - direct_url
          description: The kind of target. Only `direct_url` is supported in v1.
        url:
          type: string
          format: uri
          description: The product or checkout URL the agent should purchase from.
        request:
          type: string
          minLength: 1
          maxLength: 4000
          description: >-
            Optional natural-language instruction (e.g. variant, size,
            quantity).
          example: buy the medium in black
        merchantContext:
          type: string
          minLength: 1
          maxLength: 4000
          description: >-
            Optional free-text guidance for how the agent should navigate this
            specific merchant's checkout when the default flow doesn't work.
    PurchaseConstraints:
      type: object
      required:
        - maxCost
      properties:
        maxCost:
          allOf:
            - $ref: '#/components/schemas/Money'
          description: >-
            Hard maximum the checkout may spend. The checkout fails with
            `max_cost_exceeded` rather than exceeding it.
    CheckoutMetadata:
      type: object
      additionalProperties:
        type: string
      description: Optional string key/value pairs echoed back on the checkout.
    CheckoutStatus:
      type: string
      enum:
        - queued
        - running
        - awaiting_user_action
        - succeeded
        - failed
        - cancelled
      description: Lifecycle state. `succeeded`, `failed`, and `cancelled` are terminal.
    IntentPackUsage:
      type: object
      description: >-
        Present on the checkout view when a pack drove the run. The pack id,
        merchant name, and phases used are captured on the run so they survive a
        later edit or deletion of the pack.
      required:
        - packId
        - merchantDisplayName
        - phasesUsed
      properties:
        packId:
          type: string
          format: uuid
          description: The pack that was applied.
        merchantDisplayName:
          type: string
          description: The merchant display name from the pack, as it was at run time.
        phasesUsed:
          type: array
          items:
            type: string
          description: Ids of the phases the agent actually used during this checkout.
    PendingUserAction:
      type: object
      description: >-
        Present when `status` is `awaiting_user_action`. Render a form from
        `responseSchema` and submit matching `values`.
      required:
        - id
        - intentId
        - message
        - responseSchema
        - createdAt
        - expiresAt
      properties:
        id:
          type: string
          format: uuid
          description: The action id — pass it as `{actionId}` in the path when responding.
        intentId:
          type: string
          format: uuid
        message:
          type: string
          description: Human-readable description of what's being asked.
        responseSchema:
          $ref: '#/components/schemas/JsonSchema'
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
          description: >-
            After this time the action expires and the checkout fails with
            `user_action_expired`.
    Receipt:
      type: object
      description: Present when `status` is `succeeded`.
      required:
        - total
        - capturedAt
      properties:
        total:
          $ref: '#/components/schemas/Money'
        capturedAt:
          type: string
          format: date-time
        merchantOrderId:
          type: string
        evidence:
          type: object
          properties:
            confirmationUrl:
              type: string
              format: uri
            confirmationText:
              type: string
    Failure:
      type: object
      description: Present when `status` is `failed`.
      required:
        - reason
        - message
        - failedAt
      properties:
        reason:
          type: string
          enum:
            - max_cost_exceeded
            - user_cancelled
            - user_action_expired
            - automation_failed
        message:
          type: string
        failedAt:
          type: string
          format: date-time
    ProgressItem:
      type: object
      description: >-
        A single timeline entry describing what the browser session is doing.
        Use `progressItems` to render live progress.
      required:
        - kind
        - id
        - intentId
        - sequence
        - label
        - startedAt
      properties:
        kind:
          type: string
          enum:
            - step
            - user_action
            - intent_started
            - intent_failed
            - intent_cancelled
        status:
          type: string
          description: >-
            Item status (e.g. `running`, `succeeded`, `failed`, `waiting`,
            `cancelled`), depending on `kind`.
        id:
          type: string
          format: uuid
        intentId:
          type: string
          format: uuid
        sequence:
          type: integer
          minimum: 0
        label:
          type: string
          maxLength: 120
        summary:
          type: string
          maxLength: 500
        startedAt:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time
    Browser:
      type: object
      description: The live browser session the agent is driving.
      required:
        - embedUrl
        - permissions
      properties:
        embedUrl:
          type: string
          description: >-
            URL to embed the live session in an `<iframe>`. May be relative to
            the Crossmint origin — resolve it against the API base URL before
            use.
        permissions:
          type: array
          items:
            type: string
            enum:
              - read
              - write
          description: Whether the embedded view is read-only or interactive.
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        error:
          type: string
        message:
          type: string
    Money:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: string
          description: Decimal amount as a string, e.g. `"100.00"`.
          example: '100.00'
        currency:
          type: string
          minLength: 3
          maxLength: 3
          description: 3-letter ISO 4217 currency code.
          example: USD
    JsonSchema:
      type: object
      description: >-
        A JSON Schema (object root with `properties`) describing the values a
        user-action submission must provide. Render it dynamically — do not
        hardcode fields.
      additionalProperties: true
  responses:
    BadRequest:
      description: The request body or parameters were invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: >-
        Missing or invalid authentication. A valid `X-API-KEY` and
        `Authorization: Bearer <jwt>` are both required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        The API key lacks the required scope, or Agent Checkouts is not enabled
        for this project.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: >-
        The checkout could not be started or the browser-automation service is
        unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Client-side API key (`ck_...`) with the `agent-checkouts.*` scopes.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT identifying the end user, issued by an external auth provider your
        project trusts.

````