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 the user’s saved merchant session; send it on every checkout for that user. 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

Buy a Product

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."
  }
}
'

202

{
  "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>"
  }
}

Authorizations

apiKey & userJwtapiKey

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

202

application/json

The checkout run was accepted.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

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