Run your first errand

Private preview: this is rolling out and may not be available on your account yet.

An errand is a purchase you ask your agent to make, run within a Stamped Mandate. You ask in your own words. You sign the errand’s bounds: the most it may spend, the currency, any conditions, and when the authorisation lapses. Then Sumvin searches, checks the merchant, watches for your conditions, and settles the purchase. Nothing is searched until you sign, and once you have signed, a match within your bounds is bought without asking you again. Sumvin is a Visa Intelligent Commerce Launch Partner, and errands are built on Visa Intelligent Commerce.

Coming soon: payments arrive in a fast-follow release.

Payments aren’t part of this preview. They arrive in a fast-follow release, with its own waitlist.

The shape of an errand

You sign once, before anything is searched. With a repeat errand, one signature covers several matching errands. See Repeat errands.

Run it

In your agent (MCP, recommended)
In the terminal (CLI, for developers)

Ask

Tell your agent what you want, in your own words. It starts an errand with errand_create, keeping your phrasing, because that is what the errand is checked against later.Starting an errand doesn’t search for anything or authorise any spending. It needs the most it may spend and the currency, because that is what you sign.

Answer any question

If the errand needs more detail, your agent asks you, for example about size or budget. Answer in the conversation; your agent passes your answers on with errand_action.

Sign the errand

Before anything is searched, the errand waits for you at pending_approval. You see what you’re signing: your ask, the most it may spend, any conditions, and when the authorisation lapses. Your agent can’t sign for you; you sign it yourself.Signing an errand from the connector is coming soon. It arrives with payments. Until then, an errand you run from the connector stays waiting at this step.

Follow progress

Once you’ve signed, Sumvin searches, checks the merchant, watches for your conditions, and settles the purchase, without asking you again. Ask your agent how it’s going. It reads the errand with errand_query and its history with errand_events_query.

Ask

sumvin errand create "Reorder my usual coffee beans" --max 30 --currency GBP

Errand <errand-id> created (qualifying).

The agent is now qualifying your request.
Run `sumvin errand get` to follow its progress.

--max (the most it may spend, such as 30 or 29.50) and --currency (a three-letter code, such as GBP or USD) are required, because they are what you sign. Creating the errand authorises nothing.The command also prints a key. If your connection drops before you see a reply, run the same command again with --idempotency-key <printed-key> and no second errand is created.

Answer any question

sumvin errand get <errand-id>

Questions appear numbered under Clarification questions. Answer them by number:

sumvin errand clarify <errand-id> --answer 1="The 1kg bag"

Sign the errand

When the status is pending_approval, nothing has been searched yet. Review the errand’s bounds and sign:

sumvin errand approve <errand-id>

The CLI shows the statement, the spend limit, any conditions and the expiry, and asks you to confirm. A match found within these bounds is bought without asking you again. The first time, you set up a signing key; see Stamped Mandate. To decline, run sumvin errand reject <errand-id>.

Follow progress

sumvin errand events <errand-id>

After you sign, the errand searches, checks the merchant, watches for your conditions, and settles. Events are listed oldest first: status changes, questions sent and answered, your signature requested and received, and the purchase starting and finishing.

What you’ll see

Status	What it means
`qualifying`	Reading your ask.
`pending_clarification`	Waiting for you to answer a question, before you sign.
`pending_approval`	Waiting for you to sign the errand’s bounds. Nothing has been searched yet.
`approved`	You signed. The search is about to start.
`searching`	Looking for options within what you signed.
`validating`	Checking an option, and the merchant selling it, against what you signed.
`monitoring`	Watching for the conditions you set, such as a price or stock level.
`executing`	Buying now.
`completed`	Settled. Done.
`failed`	It didn’t go through. The errand says why.
`expired`	It ran out of time, including when you don’t sign in time.
`cancelled`	You cancelled or declined it, or its mandate was revoked.

completed, failed, expired and cancelled are final. A signed errand isn’t a completed purchase yet: it goes on to search, check the merchant, watch and settle, within the limit you signed and only while its conditions hold. It doesn’t ask you again.

Stop an errand

You can stop an errand at any point before it’s final. Ask your agent to cancel it, or run:

sumvin errand cancel <errand-id>

What can go wrong

Errands aren't available on your account

Starting errands is rolling out. If your agent or the CLI says your account can’t start errands yet, the rest of your setup is unaffected.

Your answer was refused

An errand takes answers only while it’s waiting on a question. Check its status first.

The mandate expired before you signed

An errand you don’t sign in time can’t be signed any more. Nothing was searched or spent. If it’s still waiting, decline it, then start a new one.

Something happened you didn't expect

Read the errand’s history: ask your agent, or run sumvin errand events <errand-id>. If the errand was cancelled because you revoked its mandate, the history says so.

Try asking your agent: “Reorder my usual coffee beans.”

Start here

Connect your agent

Use the CLI

Your first

Run your first errand

The shape of an errand

Run it

What you’ll see

Stop an errand

What can go wrong

​The shape of an errand

​Run it

​What you’ll see

​Stop an errand

​What can go wrong

The shape of an errand

Run it

What you’ll see

Stop an errand

What can go wrong