> ## 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.item.updated

> One booking of a trip moved: it started booking, was confirmed, waits for your customer, or did not book.

One booking of a trip moved. Update that line of your trip tracker the moment it changes. Agentcard sends one `plan.item.updated` each time a flight, hotel or car in the plan changes state.

```json theme={null}
{
  "id": "evt_3a5c7e9b1d2f",
  "type": "plan.item.updated",
  "created": 1793318340,
  "livemode": true,
  "data": {
    "plan_id": "plan_8f2k4c1a9e7b3d5f6a2c8e0b",
    "version": 5,
    "user_id": "usr_8f3k2m",
    "external_user_id": "shopper-42",
    "conversation_id": "conv_9a8b7c6d5e4f3a2b1c0d9e8f",
    "item": {
      "key": "hotel",
      "kind": "hotel",
      "state": "needs_input",
      "previous_state": "booking",
      "name": "Memmo Alfama, 5 nights",
      "price_cents": 128400,
      "asked_cents": 131900,
      "confirmation": null,
      "depends_on": ["flight"],
      "reason": "price_changed"
    }
  }
}
```

## Follow a booking's states

| `state` | What happened |
| - | - |
| `approved` | Your customer approved the booking, and Agentcard books it once the bookings before it are confirmed. |
| `booking` | Agentcard is making the booking now. |
| `pending` | The supplier has not said yet whether the booking went through. Agentcard never books it a second time while it waits. |
| `confirmed` | The booking is confirmed. `confirmation` carries the supplier's number. |
| `needs_input` | The booking waits for your customer. `reason` says why. |
| `failed` | The supplier refused the booking, and nothing was charged for it. |
| `skipped` | The booking was not made, because a booking before it did not go through or nobody answered in time. |

## Answer a booking that waits

A `needs_input` booking carries one of two reasons:

* `price_changed`: the supplier asks a different price than your customer approved, in `asked_cents`. Agentcard never books at a price your customer did not see, up or down.
* `approval_required`: the payment asks your customer to approve it on their device.

Send your customer's answer to a changed price with `POST /buy/plans/:id/items/:key/answer`:

```bash theme={null}
curl -X POST https://api.agentcard.sh/buy/plans/plan_8f2k4c1a9e7b3d5f6a2c8e0b/items/hotel/answer \
  -H "Authorization: Bearer $SHOPPER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"answer": "accept_price"}'
```

`accept_price` books the item at the new price when the new price fits inside what your customer approved for the whole trip, which leaves room when another booking came in under its quote. A new price above that answers 409, and `difference_cents` is the amount above what the approval still covers:

```text theme={null}
{"error":"needs_approval","code":"needs_approval","difference_cents":3500}
```

The booking then keeps waiting, because a plan's approved total cannot be raised yet. Your customer can skip it instead.

`skip` leaves the booking unbooked, along with the bookings that wait on it. Bookings already confirmed stay booked: Agentcard never cancels one for your customer.

## Read a refused answer

| `code` | Status | What it means | What to do next |
| - | - | - | - |
| `needs_approval` | 409 | The new price is above what the trip's approval still covers, by `difference_cents`. A plan's approved total cannot be raised yet. | Tell your customer the booking costs more, and send `skip` if they decline it. |
| `not_waiting` | 409 | The booking is not waiting for an answer, or it waits on a payment approval on your customer's device. | Read the plan with `GET /buy/plans/:id` and follow the booking's `state`. |
| `hold_ended` | 409 | The answer came after `hold_until`. The bookings that waited are let go unbooked, and this endpoint can no longer book them. | Tell your customer those bookings were not made and nothing was charged for them. |
| `invalid_answer` | 400 | The body named no answer Agentcard takes. | Send `{"answer": "accept_price"}` or `{"answer": "skip"}`. |
| `plan_not_found` | 404 | No plan with this id belongs to this shopper and app. | Check the plan id and the shopper's access token. |

## Keep the newest version per booking

`version` is the plan's version at the change. Keep the highest `version` you have seen for each `item.key`, so a retried delivery for the hotel still applies after a newer delivery for the car.


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