Buy

curl --request POST \
  --url https://api.agentcard.sh/buy \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ask": "a 16 oz bag of Colombian ground coffee from Amazon, ship it to 1900 Jefferson St, San Francisco"
}
'

{
  "conversation_id": "<string>",
  "status": "needs_input",
  "reply": "<string>",
  "messages": [
    "<string>"
  ],
  "message_id": "<string>",
  "cart": {
    "merchant": "<string>",
    "merchant_name": "<string>",
    "items": [
      {
        "name": "<string>",
        "qty": 123,
        "product_id": "<string>",
        "priceCents": 123
      }
    ],
    "serviceFeesCents": 123,
    "tipCents": 123,
    "totalCents": 123,
    "hash": "<string>"
  },
  "carts": [
    {
      "merchant": "<string>",
      "merchant_name": "<string>",
      "items": [
        {
          "name": "<string>",
          "qty": 123,
          "product_id": "<string>",
          "priceCents": 123
        }
      ],
      "serviceFeesCents": 123,
      "tipCents": 123,
      "totalCents": 123,
      "hash": "<string>"
    }
  ],
  "placements": [
    {
      "merchant": "<string>",
      "merchant_name": "<string>",
      "status": "needs_input",
      "reply": "<string>",
      "order_id": "<string>",
      "payment_source": {
        "source": "balance",
        "brand": "<string>",
        "last4": "<string>"
      },
      "decline_code": "<string>",
      "approval_url": "<string>",
      "charge_status": "none",
      "error_code": "<string>"
    }
  ],
  "catalog": {
    "merchant": "<string>",
    "merchant_name": "<string>",
    "store": {
      "id": "<string>",
      "name": "<string>"
    },
    "items": [
      {
        "id": "<string>",
        "name": "<string>",
        "priceCents": 123
      }
    ],
    "as_of": "2023-11-07T05:31:56Z"
  },
  "error_code": "<string>",
  "order_id": "<string>",
  "payment_source": {
    "source": "balance",
    "brand": "<string>",
    "last4": "<string>"
  },
  "decline_code": "<string>",
  "approval_url": "<string>",
  "charge_status": "none",
  "unmatched": [
    {
      "merchant": "<string>",
      "requested": "<string>",
      "reason": "not_found",
      "detail": "<string>",
      "at": "2023-11-07T05:31:56Z"
    }
  ]
}

{
  "error": "<string>",
  "hint": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "cart changed since that hash was issued — verify the current carts and confirm their hashes",
  "conversation_id": "cmsq18x2m00a1",
  "cart": {
    "merchant": "retail",
    "merchant_name": "Amazon",
    "items": [
      {
        "name": "Cafe Mesa de los Santos Colombian Ground Coffee, 16 oz",
        "qty": 1,
        "priceCents": 2450
      }
    ],
    "serviceFeesCents": 61,
    "tipCents": 0,
    "totalCents": 2511,
    "hash": "31d8a6e0c47b92f5"
  },
  "carts": [
    {
      "merchant": "retail",
      "merchant_name": "Amazon",
      "items": [
        {
          "name": "Cafe Mesa de los Santos Colombian Ground Coffee, 16 oz",
          "qty": 1,
          "priceCents": 2450
        }
      ],
      "serviceFeesCents": 61,
      "tipCents": 0,
      "totalCents": 2511,
      "hash": "31d8a6e0c47b92f5"
    }
  ]
}

{
  "error": "<string>",
  "conversation_id": "<string>",
  "placements": [
    {}
  ],
  "error_code": "<string>"
}

{
  "error": "<string>",
  "code": "turn_lock_unavailable",
  "conversation_id": "<string>"
}

POST

buy

curl --request POST \
  --url https://api.agentcard.sh/buy \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ask": "a 16 oz bag of Colombian ground coffee from Amazon, ship it to 1900 Jefferson St, San Francisco"
}
'

{
  "conversation_id": "<string>",
  "status": "needs_input",
  "reply": "<string>",
  "messages": [
    "<string>"
  ],
  "message_id": "<string>",
  "cart": {
    "merchant": "<string>",
    "merchant_name": "<string>",
    "items": [
      {
        "name": "<string>",
        "qty": 123,
        "product_id": "<string>",
        "priceCents": 123
      }
    ],
    "serviceFeesCents": 123,
    "tipCents": 123,
    "totalCents": 123,
    "hash": "<string>"
  },
  "carts": [
    {
      "merchant": "<string>",
      "merchant_name": "<string>",
      "items": [
        {
          "name": "<string>",
          "qty": 123,
          "product_id": "<string>",
          "priceCents": 123
        }
      ],
      "serviceFeesCents": 123,
      "tipCents": 123,
      "totalCents": 123,
      "hash": "<string>"
    }
  ],
  "placements": [
    {
      "merchant": "<string>",
      "merchant_name": "<string>",
      "status": "needs_input",
      "reply": "<string>",
      "order_id": "<string>",
      "payment_source": {
        "source": "balance",
        "brand": "<string>",
        "last4": "<string>"
      },
      "decline_code": "<string>",
      "approval_url": "<string>",
      "charge_status": "none",
      "error_code": "<string>"
    }
  ],
  "catalog": {
    "merchant": "<string>",
    "merchant_name": "<string>",
    "store": {
      "id": "<string>",
      "name": "<string>"
    },
    "items": [
      {
        "id": "<string>",
        "name": "<string>",
        "priceCents": 123
      }
    ],
    "as_of": "2023-11-07T05:31:56Z"
  },
  "error_code": "<string>",
  "order_id": "<string>",
  "payment_source": {
    "source": "balance",
    "brand": "<string>",
    "last4": "<string>"
  },
  "decline_code": "<string>",
  "approval_url": "<string>",
  "charge_status": "none",
  "unmatched": [
    {
      "merchant": "<string>",
      "requested": "<string>",
      "reason": "not_found",
      "detail": "<string>",
      "at": "2023-11-07T05:31:56Z"
    }
  ]
}

{
  "error": "<string>",
  "hint": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "cart changed since that hash was issued — verify the current carts and confirm their hashes",
  "conversation_id": "cmsq18x2m00a1",
  "cart": {
    "merchant": "retail",
    "merchant_name": "Amazon",
    "items": [
      {
        "name": "Cafe Mesa de los Santos Colombian Ground Coffee, 16 oz",
        "qty": 1,
        "priceCents": 2450
      }
    ],
    "serviceFeesCents": 61,
    "tipCents": 0,
    "totalCents": 2511,
    "hash": "31d8a6e0c47b92f5"
  },
  "carts": [
    {
      "merchant": "retail",
      "merchant_name": "Amazon",
      "items": [
        {
          "name": "Cafe Mesa de los Santos Colombian Ground Coffee, 16 oz",
          "qty": 1,
          "priceCents": 2450
        }
      ],
      "serviceFeesCents": 61,
      "tipCents": 0,
      "totalCents": 2511,
      "hash": "31d8a6e0c47b92f5"
    }
  ]
}

{
  "error": "<string>",
  "conversation_id": "<string>",
  "placements": [
    {}
  ],
  "error_code": "<string>"
}

{
  "error": "<string>",
  "code": "turn_lock_unavailable",
  "conversation_id": "<string>"
}

Authorizations

Authorization

string

header

required

The user's connection access_token (user authentication), or an org-minted buy_token for org-owned accounts.

Body

application/json

Option 1
Option 2

ask

string

required

What the user wants, in plain language. Required unless the call is a confirm.

Minimum string length: 1

Pattern: \S

conversation_id

string

The thread to continue. A confirm always requires it.

Minimum string length: 1

confirm

A cart hash from a previous response (16 hex characters), or an array of hashes to place several carts. An array confirm cannot carry an ask in the same call.

Pattern: ^[0-9a-f]{16}$

payment_source

enum<string>

Pay the confirmed cart(s) with the user's own vaulted card, whatever the user's wording: the confirm pauses with decline_code vault_approval_required and an approval_url, the user approves on their device, and the same confirm places the order. Confirm-only. Omit it and the loop keeps its default source.

Available options:

vault

Response

One turn of the purchase conversation, in the fixed envelope.

The fixed response envelope. Every field is present on every response, null when empty.

conversation_id

string

required

Thread it back on every follow-up. Returned on the first call too.

status

enum<string>

required

needs_input is progress, not failure: the reply is a question or a cart waiting on confirmation.

Available options:

needs_input,

order_placed,

partially_placed,

declined

string

required

The assistant's turn as prose, ready to show a human.

messages

string[]

required

The same turn split into ordered bubbles for chat surfaces.

message_id

string

required

cart

object | null

required

The most recently shown cart. Null when no cart is on the table.

Show child attributes

carts

object[]

required

Every open cart in the conversation, oldest first. A conversation can hold carts at several merchants.

Show child attributes

placements

object[] | null

required

Per-cart outcomes of a multi-cart confirm; null on every other call. Partial success is representable here.

Show child attributes

catalog

object | null

required

The last product search as data, with a freshness stamp. Null when nothing fresh was searched.

Show child attributes

error_code

string | null

required

Machine-readable failure code when something went wrong.

order_id

string | null

required

Set when this call placed an order: the merchant's order id, or Agentcard's when the merchant returns none. The same key as order.orderId in GET /cards/transactions/by-payment-method and order_id on order.placed. Null on a multi-cart confirm (see placements).

payment_source

object | null

required

What paid, or what would have paid. brand and last4 are the user's own card for added_card, vault and stored_payment_method; null for balance and company_balance, where no card of theirs is in the flow. Null when no checkout ran or it refused before resolving the source.

Show child attributes

decline_code

string | null

required

The machine code behind a declined: a gate reason (byoc_approval_required, vault_approval_required, sandbox_mode, per_txn_max_exceeded, card_limit_reached, ...) or a merchant code (items_unavailable, pos_cart_validation). Null on success and on recoverable errors.

approval_url

string | null

required

The link to send the user when the attempt paused for their bank's or Vault's approval. Send the same confirm again once they approve.

charge_status

enum<string> | null

required

Whether money moved on this call's checkout: none (nothing charged, nothing pending: every decline, approval pause and refusal answered before money moved), confirming (placed, charge still confirming), settled, or unknown (the attempt may have moved money and Agentcard cannot yet say; do not retry, read the conversation's orders, then support). Null when no checkout ran.

Available options:

none,

confirming,

settled,

unknown,

null

unmatched

object[]

required

Asks that did not make it into a cart, cumulative for the conversation, with machine-derived reasons and the moment each happened. An entry leaves only when the same line later lands in a cart; placing an order does not clear it. Never inferred from the reply. Always an array.

Show child attributes

Overview

Access tokens

Connections

Vault

Purchases

Cards

Identity verification

Wallet

Wallet links

Webhook endpoints

Embed origins

Blooio connection

Authorizations

Body

Response