curl --request POST \
  --url https://staging.crossmint.com/api/unstable/agent-checkouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "constraints": {
    "maxCost": {
      "amount": "20.00",
      "currency": "USD"
    }
  },
  "request": {
    "startUrl": "https://shop.example.com/products/sticker-pack",
    "task": "Go to the checkout for one sticker pack, with standard delivery."
  }
}
'

{
  "browser": {
    "embedUrl": "<string>",
    "permissions": [
      "read"
    ]
  },
  "createdAt": "<string>",
  "input": {
    "constraints": {
      "maxCost": {
        "amount": "<string>",
        "currency": "<string>"
      }
    },
    "request": {
      "startUrl": "<string>",
      "task": "<string>"
    },
    "browser": {
      "cdp": {
        "redacted": true
      },
      "location": {
        "countryCode": "<string>",
        "type": "country"
      },
      "profileId": "<string>"
    },
    "buyerProfileId": "<string>",
    "merchantGuidance": "<string>"
  },
  "reason": "accounting_unavailable",
  "requiredAction": null,
  "revision": 4503599627370495,
  "runId": "<string>",
  "status": "failed",
  "continuedIn": {
    "runId": "<string>"
  },
  "continues": {
    "runId": "<string>"
  }
}

{
  "error": true,
  "message": "<string>",
  "code": "<string>",
  "parameters": {}
}

{
  "error": true,
  "message": "<string>",
  "code": "<string>",
  "parameters": {}
}

{
  "error": true,
  "message": "<string>",
  "code": "<string>",
  "parameters": {}
}

{
  "error": true,
  "message": "<string>",
  "code": "<string>",
  "parameters": {}
}

{
  "error": true,
  "message": "<string>",
  "code": "<string>",
  "parameters": {}
}

{
  "error": true,
  "message": "<string>",
  "code": "<string>",
  "parameters": {}
}

Agent Checkouts

Create Agent Checkout

Starts a checkout run: the agent opens startUrl, works toward task within constraints, and reports back through the run’s messages. Without a startUrl, task is required: the run finds products for it and asks the buyer to choose one before it opens a page. A buyerProfileId supplies identity and shipping details; browser.profileId reuses a saved merchant session. The response is the run in queued status. Poll Get Agent Checkout or stream its messages to follow it.

API scope required: agent-checkouts.create

POST

unstable

agent-checkouts

curl --request POST \
  --url https://staging.crossmint.com/api/unstable/agent-checkouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "constraints": {
    "maxCost": {
      "amount": "20.00",
      "currency": "USD"
    }
  },
  "request": {
    "startUrl": "https://shop.example.com/products/sticker-pack",
    "task": "Go to the checkout for one sticker pack, with standard delivery."
  }
}
'

{
  "browser": {
    "embedUrl": "<string>",
    "permissions": [
      "read"
    ]
  },
  "createdAt": "<string>",
  "input": {
    "constraints": {
      "maxCost": {
        "amount": "<string>",
        "currency": "<string>"
      }
    },
    "request": {
      "startUrl": "<string>",
      "task": "<string>"
    },
    "browser": {
      "cdp": {
        "redacted": true
      },
      "location": {
        "countryCode": "<string>",
        "type": "country"
      },
      "profileId": "<string>"
    },
    "buyerProfileId": "<string>",
    "merchantGuidance": "<string>"
  },
  "reason": "accounting_unavailable",
  "requiredAction": null,
  "revision": 4503599627370495,
  "runId": "<string>",
  "status": "failed",
  "continuedIn": {
    "runId": "<string>"
  },
  "continues": {
    "runId": "<string>"
  }
}

{
  "error": true,
  "message": "<string>",
  "code": "<string>",
  "parameters": {}
}

{
  "error": true,
  "message": "<string>",
  "code": "<string>",
  "parameters": {}
}

{
  "error": true,
  "message": "<string>",
  "code": "<string>",
  "parameters": {}
}

{
  "error": true,
  "message": "<string>",
  "code": "<string>",
  "parameters": {}
}

{
  "error": true,
  "message": "<string>",
  "code": "<string>",
  "parameters": {}
}

{
  "error": true,
  "message": "<string>",
  "code": "<string>",
  "parameters": {}
}

Agent Checkouts uses production API keys. A staging key gets 403 with the message "Agent Checkouts is only available in production". See Test Agent Checkouts.

Authorizations

X-API-KEY

string

header

required

API key required for authentication

Authorization

string

header

required

The end user's JWT, sent as Authorization: Bearer <JWT> together with a client-side API key. Validated against the project's external JWT configuration.

Headers

x-crossmint-user-id

string

Server-side subject to act on behalf of. Ignored for client-side user auth.

Body

application/json

constraints

object

required

maxCost is the most this run may authorize for the purchase, compared only in its own currency. When the merchant charges in another currency, a card payment is requested for the exact total in that currency, without conversion or a check against maxCost; the buyer's approval of that amount is the check.

Show child attributes

request

object

required

Show child attributes

browser

object

Browser profile and requested location, or a caller-owned browser; provide at least one property. A CDP connection excludes the other properties

Show child attributes

buyerProfileId

string

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

merchantGuidance

string

Required string length: 1 - 20000

Response

The checkout run was accepted.

browser

object | null

required

Show child attributes

createdAt

string

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

input

object

required

Show child attributes

reason

enum<string>

required

Available options:

accounting_unavailable,

browser_location_unsupported,

browser_session_lost,

cancelled,

cost_limit,

input_expired,

model_error,

reconciliation_required,

runtime_error

revision

integer

required

Monotonically increasing version of this run snapshot. When combining polling and stream updates, retain the snapshot with the greatest revision; values may skip and have no meaning beyond ordering

Required range: 0 <= x <= 9007199254740991

runId

string

required

Minimum string length: 1

status

enum<string>

required

Available options:

failed

continuedIn

object

The run started at the alternative the buyer chose after this run could not buy; that run buys it

Show child attributes

continues

object

The run this one continues: it buys the alternative its buyer chose after that run could not buy

Show child attributes

Introduction

Agent Cards

Agent Wallets and Onramps

Agent Checkouts

API Reference

Create Agent Checkout

Authorizations

Headers

Body

Response