{"uid":"cap_O4e_LdvNFMiu74wWVdbsU","slug":"butiful-agent-commerce-purchase-acc2eec0","name":"Butiful Agent Commerce – Purchase","description":"Agent-ready commerce for Butiful. Discover available products, get Shopify-priced quotes, and purchase physical products using x402/USDC with Shopify handling inventory, orders, shipping, and fulfillment.","url":"https://agent.butiful.org/api/agent/purchase","method":"POST","headers":{},"bodySchema":{"type":"object","required":["email","purchaseToken","idempotencyKey"],"properties":{"email":{"type":"string","description":"Shopper email for order confirmation and shipping updates."},"phone":{"type":"string"},"purchaseToken":{"type":"string","description":"The purchaseToken of the chosen shippingOption from POST /api/agent/quote. It binds items, destination, shipping method and the exact total."},"idempotencyKey":{"type":"string","description":"Client-generated unique key (UUID recommended). Retrying with the same key never creates a second order."}}},"responseSchema":{"ok":true,"ref":"BAX-7K3M9QW2XZ","order":{"id":"gid://shopify/Order/6001234567890","name":"#1234"},"status":"completed","message":"Order placed with Butiful. Fulfillment and shipping notifications follow the store's normal process.","payment":{"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payer":"0xabc...","amount":"20400000","network":"eip155:8453","amountUsd":"20.40","transaction":"0x123..."},"receipt":{"token":"a1b2c3...","statusUrl":"https://agent.butiful.org/api/agent/orders/BAX-7K3M9QW2XZ?receipt=a1b2c3..."},"shipping":{"method":"Economy","destinationCountry":"US"}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.01/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_AwekuLdtEVlYm7tCWXPM2","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Executes a physical product purchase on Butiful's Shopify-backed store using a pre-quoted purchase token, paying via x402/USDC on Base, and triggering Shopify fulfillment.","exampleAgentPrompt":"Place the Butiful order using purchase token 'tok_abc123', my email jane@example.com, and a fresh idempotency key — charge it via USDC and get me the order confirmation and receipt URL.","exampleUseCases":[{"title":"Automated crypto checkout for physical goods","prompt":"Go ahead and finalize my Butiful order — use purchase token 'tok_xyz789', send confirmation to mike@example.com, and generate a new idempotency key so we don't accidentally double-order."},{"title":"Agent-driven gift purchase with retry safety","prompt":"Complete the Butiful purchase for the gift I quoted earlier — the purchase token is 'tok_gift456', confirm to sarah@example.com, and make sure you use a unique idempotency key so if it fails we can safely retry."},{"title":"Headless storefront order fulfillment","prompt":"Trigger the final checkout step on Butiful for purchase token 'tok_shop321' — ship to the US address I confirmed, send order updates to orders@myshop.com, and return the Shopify order number and receipt URL once it's done."}],"resultDescription":"Returns a Butiful order reference (e.g. BAX-7K3M9QW2XZ), Shopify order ID and name, payment details (USDC amount, transaction hash, payer address, Base network), a receipt token with a status URL for tracking, and shipping method and destination country. Order status is 'completed' on success and Shopify handles subsequent fulfillment and shipping notifications.","failureModes":["Invalid or expired purchaseToken — quote must be re-fetched from /api/agent/quote","Duplicate idempotencyKey with different parameters — returns existing order rather than creating new one","Payment failure — USDC transfer on Base rejected or insufficient balance","Invalid email format — order cannot be created without valid shopper email","Item out of stock after quote was generated — Shopify inventory conflict","Network or Shopify API error — returns error with 5xx status"],"whenToPreferThis":"Use this endpoint when you have already obtained a purchaseToken from the Butiful /api/agent/quote endpoint and are ready to commit the order. This is the final checkout step — not for browsing products or getting prices. Prefer this over generic Shopify APIs when operating in an x402/USDC agent payment context, as it handles crypto payment settlement and Shopify order creation atomically. The idempotencyKey makes it safe to retry on transient failures.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-15T12:34:09.660Z","isFirstParty":false}