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, your agent does the searching, and nothing is bought until you approve it, or until a mandate you pre-authorised allows it. 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

With a pre-authorised mandate, the approve step happens once, up front. 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 starts the search. It doesn’t authorise any spending.

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.

Approve the purchase

When a purchase is ready, the errand waits for you at pending_approval. Your agent can’t approve it; you approve it yourself, and you see what you’re approving before you sign.Approving a purchase 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

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"

Errand <errand-id> created (qualifying).

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

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"

Approve the purchase

When the status is pending_approval, review and sign:

sumvin errand approve <errand-id>

The CLI shows the statement, the spend limit and the expiry, and asks you to confirm. 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>

Events are listed oldest first: status changes, questions sent and answered, approvals requested and received, and the purchase starting and finishing.

What you’ll see

Status	What it means
`qualifying`, `searching`, `validating`	Your agent is working out what to buy.
`pending_clarification`	Waiting for you to answer a question.
`pending_approval`	Waiting for you to approve the purchase.
`approved`	You approved.
`monitoring`	Approved, and waiting for the conditions you set, such as a price or stock level.
`executing`	The purchase is being made.
`completed`	Done.
`failed`	It didn’t go through. The errand says why.
`expired`	It ran out of time.
`cancelled`	You stopped it, or you declined or revoked its mandate.

completed, failed, expired and cancelled are final. An approved errand isn’t a completed purchase yet: it carries on within the limit you signed, and only while its conditions hold.

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 approved

An expired mandate can’t be approved. Decline the errand and 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