Help / Developers

MCP

The same operations as tools, for AI agents. Each tool is named for who acts.

The MCP tools run the same code as the REST API. A tool and its route check the same role, replay the same answers and return the same JSON. Use the same API key and scopes. See Authentication.

Each tool needs the scope its route needs. Reads of orders need orders:read and changes need orders:write; the customer tools need buyers:read, buyers:write and catalog:read. See Authentication.

Who acts is in the name #

A tool's name says who acts. You never choose that with an argument.

transactions_confirm, transactions_reject, transactions_pack, transactions_fulfil, transactions_accept, transactions_refuse, transactions_mark_paid, transactions_not_received, transactions_refund and transactions_edit are the seller's decisions.
transactions_buyer_* tools are a customer's own moves, made for them. They need a buyer_id.

Every change takes an idempotency key #

Every tool that changes something needs an idempotency_key. A repeated call with the same key gets the first answer and changes nothing. Onboarding a customer is the one exception, because the phone number already makes it safe to repeat. See Idempotency.

The tools #

Read

Tool	What it does
`transactions_list`	The seller's transactions, newest first. Takes `state`, `limit` and `offset`.
`transactions_get`	One transaction.
`transactions_events`	A transaction's history, oldest first.
`transactions_find_buyer`	Finds a customer by `external_ref` or `phone`. Returns the `buyer_id` the customer tools take.
`transactions_browse`	What the shop offers, as the customer sees it. Use it before setting a cart.
`transactions_buyer_status`	A customer's transaction, or their latest, with their recent ones.
`transactions_link`	The shop's entry link.
`transactions_buyer_link`	A link to send a customer.
`transactions_settings`	The approval settings.
`transactions_fee_invoices`	Tejas's monthly fee invoices.

Act for a customer

Tool	What it does
`transactions_add_buyer`	Adds a customer as the shop's own. Does not message them.
`transactions_buyer_set_lines`	Replaces the lines of the customer's cart.
`transactions_buyer_place`	Places the cart.
`transactions_buyer_edit`	Edits one of the customer's transactions.
`transactions_buyer_cancel`	Cancels one of the customer's transactions. Cancelling a confirmed one asks first.

Decide as the seller

transactions_confirm, transactions_reject, transactions_pack, transactions_fulfil, transactions_accept, transactions_refuse, transactions_mark_paid, transactions_not_received, transactions_refund and transactions_edit. The arguments are the same as the REST bodies: transaction_id, version, reason, confirmed, amount and lines.

A good flow for an agent #

Call transactions_find_buyer, or transactions_add_buyer for a new customer.
Call transactions_browse and show the person what is there.
Call transactions_buyer_set_lines. Show the person the lines and the total.
When the person agrees, call transactions_buyer_place.

If a price moved, the cart answer says so with a price_changed problem. Show the new total and ask again before you place.

Did this page help?

Last checked: 2026-11-07