> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sumvin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run your first errand

> Ask your agent to do one thing for you; you answer any question, sign the errand's bounds, and follow it as Sumvin searches, checks the merchant, watches and settles.

export const waitlists = {
  earlyAccess: "https://sumvin.com/?interest=early_access&utm_source=docs&utm_medium=banner&utm_campaign=early_access#waitlist",
  payments: "https://sumvin.com/?interest=payments&utm_source=docs&utm_medium=banner&utm_campaign=payments#waitlist",
  openBanking: "https://sumvin.com/?interest=open_banking&utm_source=docs&utm_medium=banner&utm_campaign=open_banking#waitlist",
  developers: "https://sumvin.com/developers?interest=cli,agent_plugin&utm_source=docs&utm_medium=banner&utm_campaign=developers#access",
  verifiers: "https://sumvin.com/developers?interest=verifiers&utm_source=docs&utm_medium=banner&utm_campaign=verifiers#access"
};

<Note>
  **Private preview:** this is rolling out and may not be available on your account yet.{waitlists.earlyAccess ? <> <a href={waitlists.earlyAccess}>Request early access →</a></> : null}
</Note>

An errand is a purchase you ask your agent to make, run within a [Stamped Mandate](/get-started/first/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](https://www.visa.com/en-us/solutions/intelligent-commerce), and errands are built on Visa Intelligent Commerce.

<Note>
  **Coming soon:** payments arrive in a fast-follow release.{waitlists.payments ? <> <a href={waitlists.payments}>Join the waitlist →</a></> : " A waitlist opens shortly."}
</Note>

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

## The shape of an errand

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart LR
  A[You ask] --> C{Question?}
  C -- yes --> D[You answer]
  D --> E[You sign]
  C -- no --> E
  E --> F[Sumvin searches]
  F --> G[Checks the merchant]
  G --> H[Watches for your conditions]
  H --> I[Settles]
```

You sign once, before anything is searched. With a repeat errand, one signature covers several matching errands. See [Repeat errands](/guides/repeat-errands).

## Run it

<Tabs>
  <Tab title="In your agent (MCP, recommended)">
    <Steps>
      <Step title="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.
      </Step>

      <Step title="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`.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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`.
      </Step>
    </Steps>
  </Tab>

  <Tab title="In the terminal (CLI, for developers)">
    <Steps>
      <Step title="Ask">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        sumvin errand create "Reorder my usual coffee beans" --max 30 --currency GBP
        ```

        ```text theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        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.
      </Step>

      <Step title="Answer any question">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        sumvin errand get <errand-id>
        ```

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

        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        sumvin errand clarify <errand-id> --answer 1="The 1kg bag"
        ```
      </Step>

      <Step title="Sign the errand">
        When the status is `pending_approval`, nothing has been searched yet. Review the errand's bounds and sign:

        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        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](/get-started/first/stamped-mandate). To decline, run `sumvin errand reject <errand-id>`.
      </Step>

      <Step title="Follow progress">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        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.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sumvin errand cancel <errand-id>
```

## What can go wrong

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Your answer was refused">
    An errand takes answers only while it's waiting on a question. Check its status first.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

<Tip>**Try asking your agent:** "Reorder my usual coffee beans."</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.