Prepares a checkout at a named store and returns its envelope. merchant is the store slug search_catalog returned (required). Use when asked to buy, purchase or order. One checkout per store, all its products in line_items, each at the quantity the person wants (1 to 100); products from two stores make two checkouts; send the delivery address and the buyer's email (from the person, here or saved in your app) on this call, so the store prefills them and the first total includes delivery. Set budget_ceiling_minor here to the highest total, shipping and tax included, the person approved. Not for placing the order; complete_checkout issues the store link: the person taps it in their own browser, or you open it and complete the store's checkout. Next: if the store still asks for a detail, send what the person gives with update_checkout; read progress any time with get_checkout; when the status is ready_for_complete call complete_checkout. Error recovery: buyer_identity_contact_method_required means send buyer.email from the person with update_checkout; BUDGET_EXCEEDED means the store's total, shipping and tax included, is over budget_ceiling_minor: tell the person the total, then raise the ceiling with update_checkout once they approve, or call cancel_checkout (the checkout still exists); MERCHANT_REJECTED_INPUT names the field the store refused, so fix it and retry with a new idempotency_key; invalid_request names the field to fix; address_not_accepted means you left out merchant or sent null, so this ran RoboTrunk's test demo: add the store's merchant slug and call again; MERCHANT_NOT_FOUND means that store is not offered, so call search_catalog; out_of_stock means tell the person and call search_catalog; quote_expired or checkout_expired_or_invalid_state means call create_checkout again; idempotency_conflict means retry with a new idempotency_key or null; rate_limited means wait 60 seconds; price_not_fresh means retry in a minute; network_error means call again; UCP_MERCHANT_BUSY, UCP_MERCHANT_UNAVAILABLE or UCP_MERCHANT_REFUSED means try again shortly; payment_unavailable means call submit_feedback; any other error, including tool_layer_failure: retry once, then call submit_feedback. An explicit merchant: null runs RoboTrunk's test demo instead (one item, one test address, nothing charged). Full guide: get_tool_guide or /agent/tools.json#create_checkout Example call: {"merchant":"merchant-from-result","line_items":[{"product_id":"product-id-from-result","variant_id":"variant-id-from-result","quantity":2},{"product_id":"product-id-2-from-result","variant_id":"variant-id-2-from-result","quantity":1}],"buyer_country":"US","shipping_address":{"first_name":"first-name-from-person","last_name":"last-name-from-person","street_address":"street-from-person","address_locality":"city-from-person","address_region":"state-from-person","postal_code":"zip-code-from-person","address_country":"US"},"buyer":{"email":"email-from-person@example.com"}}
View input schema
{
"type": "object",
"properties": {
"merchant": {
"type": [
"string",
"null"
],
"maxLength": 100,
"description": "The store slug search_catalog returned with the product. Required: a call without it is refused. Only an explicit null runs RoboTrunk's one-product test demo, which sells nothing."
},
"line_items": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"description": "For a store: one line per product, up to 50, quantity 1 to 100 each; the store has the final say on stock. For the RoboTrunk demo (merchant null): exactly one line at quantity 1. Example: [{\"product_id\": \"<product_id from search_catalog>\", \"variant_id\": \"<variant_id from the same result>\", \"quantity\": 2}], the ids exactly as returned, never a page link.",
"items": {
"type": "object",
"properties": {
"product_id": {
"type": "string",
"minLength": 1,
"maxLength": 300,
"description": "The product id from `search_catalog` or `get_product`."
},
"variant_id": {
"type": [
"string",
"null"
],
"maxLength": 300,
"description": "Required for a store: the variant_id search_catalog or get_product returned. Null only in the demo (merchant null)."
},
"quantity": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "How many of this product: 1 to 100 at a store; must be 1 for the RoboTrunk demo (merchant null)."
}
},
"required": [
"product_id",
"quantity"
],
"additionalProperties": false
}
},
"buyer_country": {
"type": "string",
"pattern": "^([A-Z]{2}|unknown)$",
"default": "unknown",
"description": "Shopper's ISO country: what you know, else your best guess; unknown if none. Left out, it is read as unknown and the answer asks you to send it. Example: \"AU\", \"US\" or \"unknown\", never a country name."
},
"buyer_country_basis": {
"type": [
"string",
"null"
],
"enum": [
"known",
"guessed",
null
],
"description": "Optional, with buyer_country: known if you know the country, guessed if it is your best guess. Null if neither."
},
"shipping_address": {
"type": [
"object",
"null"
],
"description": "The person's shipping address, or null. 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.",
"properties": {
"first_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The recipient first name."
},
"last_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "The recipient last name."
},
"street_address": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "The street address."
},
"extended_address": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 200,
"description": "Apartment or suite (optional)."
},
"address_locality": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "City (town or locality outside the US)."
},
"address_region": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Two-letter state code, such as CA (state, province or region outside the US)."
},
"postal_code": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "ZIP code (postcode outside the US)."
},
"address_country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "The two-letter uppercase country code. Example: \"US\", not \"United States\"."
},
"phone_number": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 100,
"description": "The delivery contact phone number."
}
},
"required": [
"first_name",
"last_name",
"street_address",
"address_locality",
"address_region",
"postal_code",
"address_country"
],
"additionalProperties": false
},
"budget_ceiling_cents": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Demo only (merchant null); ignored at a store, so use budget_ceiling_minor there. Null otherwise."
},
"idempotency_key": {
"type": [
"string",
"null"
],
"minLength": 16,
"maxLength": 128,
"description": "16 to 128 printable ASCII characters, or null to have the tool generate one. Each internal step gets its own suffixed key, so a repeat is safe."
},
"buyer": {
"type": [
"object",
"null"
],
"description": "Buyer fields for the named merchant, including the email it requires, or null. Example: {\"email\": \"<the person's email>\"}: the <...> is the person's own address, never invented.",
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 254,
"description": "The buyer email address."
},
"first_name": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 100,
"description": "The buyer first name."
},
"last_name": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 100,
"description": "The buyer last name."
},
"phone_number": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 100,
"description": "The buyer phone number."
}
},
"required": [
"email"
],
"additionalProperties": false
},
"context": {
"type": [
"object",
"null"
],
"description": "Optional merchant context such as destination or language, or null. The currency is the merchant's own and is never taken from a caller.",
"properties": {
"address_country": {
"type": [
"string",
"null"
],
"pattern": "^[A-Z]{2}$",
"description": "The two-letter uppercase destination country code."
},
"address_region": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 100,
"description": "The destination state, such as CA (province or region outside the US)."
},
"postal_code": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 100,
"description": "The destination ZIP code (postcode outside the US)."
},
"language": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 35,
"description": "The buyer's preferred language tag."
}
},
"additionalProperties": false
},
"discounts": {
"type": [
"object",
"null"
],
"description": "Discount codes for the store, or null.",
"properties": {
"codes": {
"type": "array",
"maxItems": 10,
"description": "Up to ten printable discount codes.",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[\\x20-\\x7E]+$",
"description": "One printable ASCII discount code."
}
}
},
"required": [
"codes"
],
"additionalProperties": false
},
"budget_ceiling_minor": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 9007199254740991,
"description": "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."
},
"budget_ceiling_currency": {
"type": [
"string",
"null"
],
"pattern": "^[A-Z]{3}$",
"description": "The ISO-4217 currency of the ceiling, or null for the merchant's own. Any other is refused, naming the merchant's."
},
"shopping_session_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
"description": "Optional server-issued shopping session correlation ID. It is not purchase authority."
}
},
"required": [
"merchant",
"line_items"
],
"additionalProperties": false
}