plan.updated

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.

{
  "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.

Webhooks

Events

Read why the plan moved

Keep the newest version

Read the plan at any time

​Read why the plan moved

​Keep the newest version

​Read the plan at any time

Read why the plan moved

Keep the newest version

Read the plan at any time