curl --request POST \
  --url https://api.farthing.ai/v1/checkouts/{id}/actions/{actionId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "submit",
  "values": {
    "Size": "M",
    "Color": "Black"
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "target": {
    "url": "<string>",
    "kind": "direct_url",
    "request": "<string>",
    "merchantContext": "<string>",
    "allowedDomains": [
      "<string>"
    ],
    "countryCode": "<string>"
  },
  "constraints": {
    "maxCost": {
      "amount": "<string>",
      "currency": "USD"
    }
  },
  "metadata": {},
  "progressItems": [
    {
      "kind": "<string>",
      "label": "<string>",
      "data": {},
      "at": "2023-11-07T05:31:56Z",
      "sequence": 123
    }
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "subject": "<string>",
  "buyerProfileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "browser": {
    "embedTokenUrl": "<string>",
    "permissions": [
      "<string>"
    ]
  },
  "pendingUserAction": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "message": "<string>",
    "responseSchema": {},
    "expiresAt": "2023-11-07T05:31:56Z",
    "key": "<string>",
    "detectedTotal": {
      "amount": "<string>",
      "currency": "USD"
    }
  },
  "failure": {},
  "receipt": {
    "total": {
      "amount": "<string>",
      "currency": "USD"
    },
    "merchantOrderId": "<string>",
    "evidence": {}
  }
}

Checkouts

Answer or decline a user action

Submit the values described by the action’s responseSchema, or decline to abandon the purchase. Declining is a first-class outcome, not an error path: the run stops immediately and the checkout fails with user_cancelled.

The response is the full checkout, re-serialized, with pendingUserAction gone.

Values for card, credentials and otp actions are fully redacted in the audit record and the raw copy goes to a transient, delete-on-read store consumed by the one step that types it.

Requires the checkouts.write scope.

POST

/

v1

/

checkouts

/

{id}

/

actions

/

{actionId}

curl --request POST \
  --url https://api.farthing.ai/v1/checkouts/{id}/actions/{actionId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "submit",
  "values": {
    "Size": "M",
    "Color": "Black"
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "target": {
    "url": "<string>",
    "kind": "direct_url",
    "request": "<string>",
    "merchantContext": "<string>",
    "allowedDomains": [
      "<string>"
    ],
    "countryCode": "<string>"
  },
  "constraints": {
    "maxCost": {
      "amount": "<string>",
      "currency": "USD"
    }
  },
  "metadata": {},
  "progressItems": [
    {
      "kind": "<string>",
      "label": "<string>",
      "data": {},
      "at": "2023-11-07T05:31:56Z",
      "sequence": 123
    }
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "subject": "<string>",
  "buyerProfileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "browser": {
    "embedTokenUrl": "<string>",
    "permissions": [
      "<string>"
    ]
  },
  "pendingUserAction": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "message": "<string>",
    "responseSchema": {},
    "expiresAt": "2023-11-07T05:31:56Z",
    "key": "<string>",
    "detectedTotal": {
      "amount": "<string>",
      "currency": "USD"
    }
  },
  "failure": {},
  "receipt": {
    "total": {
      "amount": "<string>",
      "currency": "USD"
    },
    "merchantOrderId": "<string>",
    "evidence": {}
  }
}

Authorizations

Authorization

string

header

required

Authorization: Bearer ck_test_… or ck_live_…. There is no other auth scheme — no query-string keys, no request signing, no OAuth.

Path Parameters

id

string<uuid>

required

The checkout id returned at creation.

actionId

string<uuid>

required

The pendingUserAction.id from the checkout. A new action gets a new id every time — never cache one.

Body

application/json

ActionSubmit
ActionDecline

action

string

required

Allowed value: "submit"

values

object

required

Exactly the keys named in the action's responseSchema.properties. Send strings — the engines read them as strings. Required even if empty.

Response

Resolved. The full checkout, without pendingUserAction.

The whole state of one run. This is what you poll.

id

string<uuid>

required

status

enum<string>

required

succeeded, failed and cancelled are terminal; nothing leaves them.

Available options:

queued,

running,

awaiting_user_action,

succeeded,

failed,

cancelled

target

CheckoutTarget · object

required

Show child attributes

constraints

CheckoutConstraints · object

required

Show child attributes

metadata

object

required

Yours. Stored and echoed back untouched; never sent to a merchant, and not searchable.

progressItems

ProgressItem · object[]

required

Append-only, ordered by sequence. Build your UI around this rather than a spinner.

Show child attributes

createdAt

string<date-time>

required

updatedAt

string<date-time>

required

subject

string

Your own id for the end user this purchase is for. Absent when the checkout is not tagged to one. Set explicitly at creation, or stamped from the authenticating key's binding.

Example:

"user_a91f"

buyerProfileId

string<uuid>

Absent when no profile was attached, and absent after the referenced profile was deleted.

browser

object

Present once a browser session exists. Not a URL you can watch at — a pointer to the endpoint that mints one.

Show child attributes

pendingUserAction

PendingUserAction · object

Present only while the run is blocked. At most one per checkout at a time.

Show child attributes

failure

object

Show child attributes

receipt

Receipt · object

Present only on a succeeded checkout.

Show child attributes

Mint a live-view token List buyer profiles

⌘I