> ## 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; it may ask a question, you approve the purchase, and you can follow its progress until it's done.

export const waitlists = {
  earlyAccess: "",
  payments: "",
  openBanking: "",
  developers: "",
  verifiers: ""
};

<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, 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](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={null}
flowchart LR
  A[You ask] --> B[Your agent searches]
  B --> C{Question?}
  C -- yes --> D[You answer]
  D --> B
  C -- no --> E[You approve]
  E --> F[Purchase made]
  F --> G[Done]
```

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

      <Step title="Follow progress">
        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={null}
        sumvin errand create "Reorder my usual coffee beans"
        ```

        ```text theme={null}
        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.
      </Step>

      <Step title="Answer any question">
        ```bash theme={null}
        sumvin errand get <errand-id>
        ```

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

        ```bash theme={null}
        sumvin errand clarify <errand-id> --answer 1="The 1kg bag"
        ```
      </Step>

      <Step title="Approve the purchase">
        When the status is `pending_approval`, review and sign:

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

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

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

```bash theme={null}
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 approved">
    An expired mandate can't be approved. Decline the errand and 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>