Update a checkout at the store
update_checkoutSends permitted buyer, address, line-item, context, discount or fulfilment changes to a checkout at a store. Use this when a checkout from create_checkout needs correction before handoff, and to send the buyer's email and full delivery address (from the person, in this conversation or saved in your app) if you did not send them on create_checkout, so the store prefills them and the total includes delivery. Not for paying or sending payment details. Outputs: the updated rail envelope and suggested_tools. Error recovery: buyer_identity_contact_method_required means the store needs the buyer's email, so send buyer.email from the person; BUDGET_EXCEEDED means the store's total, shipping and tax included, is over the ceiling the person approved: tell the person, then raise budget_ceiling_minor once they approve or call cancel_checkout; MERCHANT_REJECTED_INPUT means the store refused one field that errors[] names, so fix it and retry with a new key; IDEMPOTENCY_CONFLICT means use a fresh key for a changed request; INVALID_REQUEST names a body or header problem; INVALID_STATE means the checkout cannot change now, so call get_checkout, then create_checkout again if it ended; CHECKOUT_NOT_FOUND means the handle is unavailable, so call create_checkout again; continuation_not_found or RUN_AUTH_REQUIRED means send checkout_id exactly as an earlier answer returned it and, if you did, call create_checkout again; PAYMENT_INSTRUMENT_NOT_ACCEPTED means remove payment data and retry; any other error, including tool_layer_failure: retry once, then call submit_feedback. Next: get_checkout to read the new status, complete_checkout when it is ready_for_complete. Full guide: get_tool_guide or /agent/tools.json#update_checkout Example call: {"checkout_id":"ucp_transcend-dev-lab_abc123","buyer":{"email":"buyer@example.test"}}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| buyer | No | Buyer details for the merchant, or null to leave them unchanged. Example: {"email": "<the person's email>"}: the <...> is the person's own address, never invented. | |
| context | No | Optional merchant context, or null to leave it unchanged. | |
| discounts | No | Discount codes for the merchant, or null to leave them unchanged. | |
| line_items | No | Replacement line items: the whole basket, every line the checkout should hold, up to 50 at a quantity of 1 to 100 each, all from this checkout's store; or null to leave the current set unchanged. Example: [{"product_id": "<product_id from search_catalog>", "variant_id": "<variant_id from the same result>", "quantity": 1}], the ids exactly as returned, never a page link. | |
| checkout_id | Yes | The UCP checkout id from create_checkout or get_checkout. | |
| idempotency_key | No | A printable ASCII key for safe retries, or null to generate one. | |
| shipping_address | No | The merchant shipping address, or null to leave it unchanged. Example: {"first_name": "<from the person>", "last_name": "<from the person>", "street_address": "<street>", "extended_address": "<apartment or suite, or null>", "address_locality": "<city>", "address_region": "<two-letter state code, such as CA>", "postal_code": "<ZIP code>", "address_country": "US"}: every <...> is the person's own value, never invented. | |
| shopping_session_id | No | Optional server-issued shopping session correlation ID. It is not purchase authority. | |
| budget_ceiling_minor | No | The total the person approved, shipping and tax included, in minor units, or null. A store total above it is refused BUDGET_EXCEEDED; ask the person. Example: 24995 for a total of 249.95. | |
| fulfillment_option_id | No | The selected fulfillment option id, or null. | |
| budget_ceiling_currency | No | The ISO-4217 currency of the ceiling, or null for the merchant's own. Any other is refused, naming the merchant's. |