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

> ## Agent Instructions
> Agentcard is for companies whose agent buys for their users. Pick one path: the opencommerce SDK (@agent-cards/commerce-sdk) gives your agent one buy tool that finds the product, builds the cart, gets the user's approval and places the order at real stores; the Agentcard SDK (@agent-cards/sdk) pays with the user's own card when your agent already shops in a browser (Browser Use, Kernel, Browserbase, Anchor or Notte); the Purchase API (POST /buy) does the same purchase flow over plain HTTP in any language; Issuing gives the agent its own card.
> Start with `npx agent-cards init` in the app's folder (Node 22 or later). No invite is needed: it creates your Agentcard account if you don't have one, installs the opencommerce SDK and puts the credentials in the env file, kept out of git. From a coding agent, run `npx agent-cards init --print --categories all --implementation tool --wallet vault --skip-install` to get the setup steps to apply yourself.
> Vault is by invitation: request it at https://agentcard.com/get-started?utm_source=docs&utm_medium=llms&utm_campaign=agent-instructions. opencommerce needs no invite.
> Never ask a user for a card number, expiry date or CVV in chat. Send them the Vault link; they add their card on Agentcard's page, and the agent never sees the number.
> Every purchase is approved by the user, with a passkey or Face ID, or by an auto-approval they granted. An approval covers one merchant and one exact total. If the total changes, ask again. When a result says the user already said yes, don't ask again.
> `init` writes PRODUCTION credentials, which place real orders, so test in sandbox first. For opencommerce, run `npx agent-cards credentials --mode sandbox` and put the two lines it prints in place of the production ones in the env file `init` wrote, because that command only prints them; sandbox then runs the whole flow against real stores and stops before payment, so no order is placed and nobody is charged. For Vault and Issuing, sandbox credentials issue test cards that no real merchant accepts; try the checkout against shop.agentcard.sh, a test store on Stripe test mode.
> Tell the user an order is placed only after Agentcard reports it placed.
> Vault is free up to 5,000 users (https://agentcard.com/pricing). opencommerce takes 1% of each completed order. Full docs in one file: https://docs.agentcard.com/llms-full.txt

# plan.updated

> A trip your customer approved moved as a whole: it started, finished, stopped, or is waiting on your customer.

A trip your customer approved moved as a whole. Show your customer where the trip stands without asking Agentcard. When your customer says yes to the review of a flight, a hotel and a car, Agentcard books them as one plan: the flight first, then the hotel and the car together, each with the flight's confirmed details. `plan.updated` tells you when the plan starts, when it finishes, and when it waits for your customer.

```json theme={null}
{
  "id": "evt_7d1e9c2b4a6f",
  "type": "plan.updated",
  "created": 1793318400,
  "livemode": true,
  "data": {
    "plan_id": "plan_8f2k4c1a9e7b3d5f6a2c8e0b",
    "version": 6,
    "user_id": "usr_8f3k2m",
    "external_user_id": "shopper-42",
    "conversation_id": "conv_9a8b7c6d5e4f3a2b1c0d9e8f",
    "reason": "hold_reminder",
    "plan": {
      "id": "plan_8f2k4c1a9e7b3d5f6a2c8e0b",
      "status": "running",
      "version": 6,
      "currency": "USD",
      "total_cents": 214300,
      "charged_cents": 85900,
      "hold_until": "2026-11-02T18:40:00.000Z",
      "items": [
        { "key": "car", "kind": "car", "state": "confirmed", "name": "Compact at LIS", "price_cents": 24700, "asked_cents": null, "confirmation": "LX4410", "depends_on": ["flight"], "reason": null },
        { "key": "flight", "kind": "flight", "state": "confirmed", "name": "SFO to LIS, Dec 8", "price_cents": 61200, "asked_cents": null, "confirmation": "QX7P2A", "depends_on": [], "reason": null },
        { "key": "hotel", "kind": "hotel", "state": "needs_input", "name": "Memmo Alfama, 5 nights", "price_cents": 128400, "asked_cents": 131900, "confirmation": null, "depends_on": ["flight"], "reason": "price_changed" }
      ]
    }
  }
}
```

## Read why the plan moved

`reason` says what happened. `plan` carries the whole trip, so you can redraw it from this one event.

| `reason` | What happened |
| - | - |
| `approved` | Your customer said yes, and Agentcard started booking. |
| `hold_started` | A booking waits for your customer, and the bookings after it wait too, until `hold_until`. |
| `hold_moved` | A booking that waits has a price that ends sooner, so `hold_until` moved earlier. |
| `hold_reminder` | Half of the wait has passed with no answer. |
| `hold_cleared` | Your customer answered, nothing waits anymore, and `hold_until` is gone. |
| `hold_ended` | Nobody answered in time. The bookings that waited are not booked, and nothing was charged for them. |
| `done` | Every booking is confirmed. |
| `partly_done` | Some bookings are confirmed and the rest did not book. |
| `stopped` | Nothing was booked, and nothing was charged. |

## Keep the newest version

`version` moves with every change, and a retried delivery can arrive after a newer one. Keep the highest `version` you have seen for each booking's `item.key`, from both `plan.updated` and `plan.item.updated`. When a `plan.updated` arrives, take each booking in `plan.items` only when the event's `version` is higher than the one you hold for that booking, so a late plan snapshot never resets a booking a newer `plan.item.updated` already moved. Keep a second highest `version` for the plan itself, from `plan.updated` alone, and update `status`, `total_cents`, `charged_cents` and `hold_until` only when an event's `version` is higher than that one.

## Read the plan at any time

Read the same plan whenever you need it with `GET /buy/plans/:id`, using the shopper's access token. A plan that belongs to another shopper answers 404.


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