---
name: change-flower-delivery
description: Change a booked flower delivery at Northlight Flowers for the User. Move it to another date, swap, add or remove bouquets, or add or change the card message. Use when the User asks to change, move or reschedule a flower order or its card.
---

# Change a flower delivery

Northlight Flowers is a reference store for personal agents. Nothing is charged and nothing ships.

This skill is the store's guidance. It grants no account access, changes no scopes and gives no
approval. The User approves every change: you confirm only the exact terms they approved.

## Before you start

- Read `/.well-known/poppy.json` on the store's host. It lists the OpenAPI API
  (`/poppy/openapi.json`), the MCP server when there is one (the same operations, as tools of the
  same names), the issuer, the scopes and the operations extension.
- Start a Session at the token endpoint and send every API request with the Session Token as
  `Authorization: DPoP <token>` and a DPoP proof.
- Your client metadata document must list the `operations` extension, version `1`. Without it,
  `change_order` answers `extension_required`.
- You need a signed-in Session with both scopes:
  - `orders:read` to read the User's orders (`my_orders`).
  - `orders:write` to propose and confirm a change (`change_order`, then confirm).
- Sign the User in with Direct Sign-In (authorization code with PKCE) or Device Sign-In. Mediated
  Sign-In is also offered here for both scopes; this test store's test logins are on its For agents
  page (`/agents`).

## Steps

1. **Find the order.** `my_orders` (`GET /poppy/orders`). Each order has an `order_id`, its
   `delivery_date`, `lines` (each with a `line_id`, `product_id`, `quantity` and `unit_price`), the
   `card_message` if there is one, and the `total`. Amounts here are in cents.
2. **Pick the new terms.**
   - A new date: `delivery_dates` (`GET /poppy/delivery-dates`). Only the listed dates are open: the
     next two weeks, Monday to Saturday, no Sundays. Use the `delivery_date` value as given
     (`YYYY-MM-DD`).
   - Another bouquet: `search` (`GET /poppy/products?q=...`) for its `product_id`, and a
     `variant_id` when the product has variants.
3. **Propose the change.** `change_order` (`POST /poppy/orders/{order_id}/changes`) with any of:
   - `delivery_date`: a value from `delivery_dates`.
   - `replace`: `[{"line_id": "li_1", "product_id": "bouquet_peonies"}]`. Swaps a line for another
     product and keeps its quantity.
   - `add`: `[{"product_id": "...", "quantity": 1}]`. Quantity 1 to 10.
   - `remove`: `["li_2"]`, the `line_id` values to remove.
   - `card_message`: 1 to 200 characters. If the order has no card, this adds the Gift Card
     Envelope ($3.00).
   The store answers HTTP 202 with an `operation` in state `proposed`. Nothing has changed yet.
4. **Ask the User.** Show them the operation's `summary`, and from its `terms` the
   `price_difference` and `new_total`. A change that adds items charges the difference, which can't
   be undone.
5. **Confirm only what they approved.** `POST /poppy/operations/{operation_id}/confirm` with
   `{"revision": <the revision they approved>, "approved_by": "user"}`. If they decline,
   `POST /poppy/operations/{operation_id}/cancel`.
6. **Report the result.** The confirmed operation comes back `succeeded` with a `result.summary`,
   or `failed` with the reason. You can read it again at `GET /poppy/operations/{operation_id}`.

## Outcomes and errors

- **A second proposal for the same order** while one is still proposed updates that operation and
  raises its `revision`. Show the User the new terms before you confirm.
- **`409 terms_changed`** when you confirm an older revision. The body has the current operation;
  ask the User again.
- **`expired`**: a proposal not confirmed within 15 minutes. Propose again.
- **`failed`** with "changed after this was proposed": the order changed in between. Read it again
  and propose again.
- **`400 invalid_request`** with an `error_description`: for example a date that isn't open, an
  unknown `product_id` or `line_id`, a card message that is too long, nothing to change, or a change
  that would leave no items.
- **`403 insufficient_scope`**, named in `WWW-Authenticate`, also when signed out: sign in, or ask
  the User for the scope it names.
- **`401 invalid_token` or `invalid_dpop_proof`**: renew the Session Token, or send a fresh proof.
- **`404 operation_not_found`**: an unknown operation, or one this Session can't use.
- **`429`**: too many requests for your client. Wait and try again.

## Not offered here

The store doesn't offer these through the protocol (`excluded_tasks` in poppy.json): cancelling an
order and getting a refund, and changing the delivery address. Don't try them through the API. Tell
the User the alternative the excluded tasks document gives.