{ "openapi": "3.1.0", "info": { "title": "Butiful Agent Commerce", "version": "1.0.0", "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.", "contact": { "email": "butifulstore1@gmail.com", "url": "https://www.butiful.org" }, "x-guidance": "Butiful is a women's fashion boutique (butiful.org) selling physical products that ship to the buyer. Flow: (1) GET /api/agent/catalog (free) to find products and their variantId values; (2) POST /api/agent/quote (free) with items + the shipping address to get Shopify's real shipping options, tax and exact totals, each with a signed purchaseToken; (3) POST /api/agent/purchase with the chosen purchaseToken, the shopper email and a unique idempotencyKey. Without payment it answers HTTP 402 whose PAYMENT-REQUIRED header/body state the exact USDC amount for that quote (x402 v2, scheme \"exact\", USDC on Base, network eip155:8453). Sign that amount and retry with PAYMENT-SIGNATURE. Payment is verified before any order is created and settled only after Shopify has accepted the basket; a real Shopify order is then created and marked paid, and the store ships it. Retrying with the same idempotencyKey never creates a second order. Quotes expire after 15 minutes; a changed store total returns 409 quote_stale and nothing is charged. Orders above 1000 USD must use the human checkout at https://www.butiful.org. Use GET /api/agent/orders/{ref}?receipt=... for fulfillment and tracking status." }, "x-agentcash-guidance": { "llmsTxtUrl": "https://agent.butiful.org/llms.txt" }, "servers": [ { "url": "https://agent.butiful.org", "description": "Butiful Agent Commerce" } ], "tags": [ { "name": "catalog", "description": "Free product discovery, read live from Shopify." }, { "name": "checkout", "description": "Quote and x402-paid purchase." }, { "name": "orders", "description": "Post-purchase status." } ], "paths": { "/api/agent/status": { "get": { "operationId": "agentStatus", "summary": "Service status and payment terms", "description": "Reports whether agent purchasing is enabled, the network/asset/recipient used for x402 payments, and discovery links.", "tags": [ "catalog" ], "security": [], "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/agent/catalog": { "get": { "operationId": "listProducts", "summary": "List purchasable products (free)", "description": "Products currently available for sale, with variants, options, prices, availability and images, read live from Shopify. Use variantId values in /api/agent/quote.", "tags": [ "catalog" ], "security": [], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Free-text search (title, tags, type), e.g. \"dress\" or \"yoga set\"." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "pageInfo.nextCursor from a previous page." } ], "responses": { "200": { "description": "Product list", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "store": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "currency": { "type": "string" } } }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "pageInfo": { "type": "object", "properties": { "hasNextPage": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true } } }, "purchaseFlow": { "type": "object" } } } } } }, "503": { "description": "Agent commerce disabled in this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/products/{handle}": { "get": { "operationId": "getProduct", "summary": "Get one product by handle (free)", "tags": [ "catalog" ], "security": [], "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product handle from the catalog or from a butiful.org product URL." } ], "responses": { "200": { "description": "Product", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "product": { "$ref": "#/components/schemas/Product" } } } } } }, "404": { "description": "Unknown handle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/quote": { "post": { "operationId": "createQuote", "summary": "Quote a basket with real shipping options and tax (free)", "description": "Shopify prices the basket for the destination: every shipping option comes back with shipping, tax, the exact total, and a signed purchaseToken valid for 15 minutes. No inventory is reserved and nothing is charged.", "tags": [ "checkout" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "examples": { "usOrder": { "summary": "One item to a US address", "value": { "items": [ { "variantId": "gid://shopify/ProductVariant/51333170921753", "quantity": 1 } ], "shippingAddress": { "firstName": "Ada", "lastName": "Lovelace", "address1": "1 Market St", "city": "San Francisco", "provinceCode": "CA", "zip": "94105", "countryCode": "US" }, "email": "ada@example.com" } } } } } }, "responses": { "200": { "description": "Quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" }, "example": { "ok": true, "quoteId": "4c0c8b2e-2a3f-4d3a-9d3f-6f5f0f0e1a2b", "expiresAt": "2026-09-08T02:15:00.000Z", "currency": "USD", "taxesIncluded": false, "items": [ { "variantId": "gid://shopify/ProductVariant/51333170921753", "name": "Basic Short Sleeve Ribbed Round Neck Top - Black / S", "sku": "wh200249565.S.Black", "quantity": 1, "unitPrice": "15.50" } ], "subtotal": "15.50", "shipTo": { "countryCode": "US", "provinceCode": "CA", "zip": "94105" }, "shippingOptions": [ { "shippingRateHandle": "eyJ...", "method": "Economy", "shipping": "4.90", "tax": "0.00", "total": "20.40", "currency": "USD", "purchaseToken": "eyJ...signed..." }, { "shippingRateHandle": "eyJ...", "method": "Standard", "shipping": "6.90", "tax": "0.00", "total": "22.40", "currency": "USD", "purchaseToken": "eyJ...signed..." } ], "next": "POST /api/agent/purchase with the purchaseToken of one shippingOption. The 402 challenge states the exact USDC amount (total x 1e6 atomic units)." } } } }, "400": { "description": "Invalid items or address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Item unavailable, no shipping to that address, or order above the agent-lane maximum.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Shopify could not price the basket. Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Agent commerce disabled in this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/purchase": { "post": { "operationId": "purchase", "summary": "Buy the quoted basket with x402 (USDC) — creates a real Shopify order", "description": "Pays for one shippingOption from /api/agent/quote. Call once without payment to receive the HTTP 402 challenge carrying the exact USDC amount for the purchaseToken, then retry with a PAYMENT-SIGNATURE header (x402 v2 HTTP transport, scheme \"exact\"). The payment is verified, the basket is re-priced and stock-checked, a Shopify draft order is created, the payment is settled, and the draft is completed as a paid order — in that order. Any failure before settlement charges nothing. Retrying with the same idempotencyKey returns the original result instead of creating another order.", "tags": [ "checkout" ], "security": [], "x-payment-info": { "price": { "mode": "dynamic", "currency": "USD", "min": "5.00", "max": "1000.00" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseRequest" }, "examples": { "purchase": { "summary": "Pay for a quoted option", "value": { "purchaseToken": "eyJ...signed...", "email": "ada@example.com", "idempotencyKey": "3f1c5d2e-9b7a-4c1d-8e2f-0a1b2c3d4e5f" } } } } } }, "responses": { "200": { "description": "Order created and paid. PAYMENT-RESPONSE carries the x402 settlement receipt.", "headers": { "PAYMENT-RESPONSE": { "schema": { "type": "string" }, "description": "Base64 x402 v2 SettlementResponse (transaction hash, network, payer)." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseResponse" }, "example": { "ok": true, "status": "completed", "ref": "BAX-7K3M9QW2XZ", "order": { "id": "gid://shopify/Order/6001234567890", "name": "#1234" }, "payment": { "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "20400000", "amountUsd": "20.40", "payer": "0xabc...", "transaction": "0x123..." }, "shipping": { "method": "Economy", "destinationCountry": "US" }, "receipt": { "token": "a1b2c3...", "statusUrl": "https://agent.butiful.org/api/agent/orders/BAX-7K3M9QW2XZ?receipt=a1b2c3..." }, "message": "Order placed with Butiful. Fulfillment and shipping notifications follow the store's normal process." } } } }, "400": { "description": "Invalid purchaseToken, email or idempotencyKey. Nothing charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required, or the attached payment did not verify/settle. PAYMENT-REQUIRED and WWW-Authenticate carry the terms; with a valid purchaseToken in the body the amount is that quote's exact total.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64 x402 v2 PaymentRequired challenge." }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "RFC 7235 challenge, scheme x402, same terms." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponse" } } } }, "409": { "description": "quote_stale (total changed), quote_expired, insufficient_stock, variant_unavailable, or in_progress (same idempotencyKey still processing). Nothing charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "order_completion_pending: payment settled but the store must finish the order manually. Includes ref and tx hash; do not pay again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Facilitator or Shopify unreachable. If settlement_unknown, check status before re-paying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Agent commerce disabled in this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/orders/{ref}": { "get": { "operationId": "getOrderStatus", "summary": "Order and fulfillment status for a purchase (free, receipt required)", "tags": [ "orders" ], "security": [], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^BAX-[A-Z2-9]{10}$" } }, { "name": "receipt", "in": "query", "required": true, "schema": { "type": "string" }, "description": "receipt.token returned by the purchase." } ], "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderStatusResponse" }, "example": { "ok": true, "ref": "BAX-7K3M9QW2XZ", "status": "completed", "order": { "name": "#1234", "createdAt": "2026-09-08T02:10:00Z", "financialStatus": "PAID", "fulfillmentStatus": "UNFULFILLED", "cancelled": false }, "fulfillments": [], "payment": { "network": "eip155:8453", "transaction": "0x123..." } } } } }, "404": { "description": "Unknown ref or wrong receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "Address": { "type": "object", "required": [ "firstName", "lastName", "address1", "city", "countryCode" ], "properties": { "firstName": { "type": "string", "maxLength": 60 }, "lastName": { "type": "string", "maxLength": 60 }, "company": { "type": "string", "maxLength": 80 }, "address1": { "type": "string", "maxLength": 120 }, "address2": { "type": "string", "maxLength": 120 }, "city": { "type": "string", "maxLength": 80 }, "provinceCode": { "type": "string", "maxLength": 10, "description": "State/province code, e.g. \"CA\". Required for US, CA, AU, JP." }, "zip": { "type": "string", "maxLength": 20, "description": "Postal code. Required for US, CA, GB, AU, JP, DE, FR." }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2, e.g. \"US\"." }, "phone": { "type": "string", "maxLength": 30, "description": "Recommended; some express shipping methods require it." } } }, "Item": { "type": "object", "required": [ "variantId" ], "properties": { "variantId": { "type": "string", "description": "Shopify ProductVariant id from /api/agent/catalog, e.g. \"gid://shopify/ProductVariant/51333170921753\"." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } } }, "Product": { "type": "object", "properties": { "productId": { "type": "string" }, "handle": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "productType": { "type": "string", "nullable": true }, "vendor": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string", "nullable": true, "description": "Human product page on butiful.org." }, "available": { "type": "boolean" }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "alt": { "type": "string", "nullable": true } } } }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } } }, "priceRange": { "type": "object", "properties": { "min": { "type": "string" }, "max": { "type": "string" }, "currency": { "type": "string" } } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "description": "Use this id in /api/agent/quote items[].variantId." }, "title": { "type": "string" }, "sku": { "type": "string", "nullable": true }, "options": { "type": "object", "additionalProperties": { "type": "string" } }, "price": { "type": "string", "description": "Decimal USD." }, "currency": { "type": "string" }, "compareAtPrice": { "type": "string", "nullable": true }, "available": { "type": "boolean" }, "requiresShipping": { "type": "boolean" }, "image": { "type": "string", "nullable": true } } } } } }, "QuoteRequest": { "type": "object", "required": [ "items", "shippingAddress" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "required": [ "variantId" ], "properties": { "variantId": { "type": "string", "description": "Shopify ProductVariant id from /api/agent/catalog, e.g. \"gid://shopify/ProductVariant/51333170921753\"." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } } } }, "shippingAddress": { "type": "object", "required": [ "firstName", "lastName", "address1", "city", "countryCode" ], "properties": { "firstName": { "type": "string", "maxLength": 60 }, "lastName": { "type": "string", "maxLength": 60 }, "company": { "type": "string", "maxLength": 80 }, "address1": { "type": "string", "maxLength": 120 }, "address2": { "type": "string", "maxLength": 120 }, "city": { "type": "string", "maxLength": 80 }, "provinceCode": { "type": "string", "maxLength": 10, "description": "State/province code, e.g. \"CA\". Required for US, CA, AU, JP." }, "zip": { "type": "string", "maxLength": 20, "description": "Postal code. Required for US, CA, GB, AU, JP, DE, FR." }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2, e.g. \"US\"." }, "phone": { "type": "string", "maxLength": 30, "description": "Recommended; some express shipping methods require it." } } }, "email": { "type": "string", "format": "email", "description": "Optional at quote time; required at purchase." } } }, "QuoteResponse": { "type": "object", "required": [ "ok", "quoteId", "expiresAt", "shippingOptions" ], "properties": { "ok": { "type": "boolean" }, "quoteId": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "taxesIncluded": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": "string", "nullable": true }, "quantity": { "type": "integer" }, "unitPrice": { "type": "string" } } } }, "subtotal": { "type": "string" }, "shipTo": { "type": "object", "properties": { "countryCode": { "type": "string" }, "provinceCode": { "type": "string", "nullable": true }, "zip": { "type": "string", "nullable": true } } }, "shippingOptions": { "type": "array", "items": { "type": "object", "required": [ "method", "total", "purchaseToken" ], "properties": { "shippingRateHandle": { "type": "string", "nullable": true }, "method": { "type": "string" }, "shipping": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string", "description": "Exact USD total you will be charged in USDC for this option." }, "currency": { "type": "string" }, "purchaseToken": { "type": "string", "description": "Signed token binding this exact basket, destination, method and total. Present it to POST /api/agent/purchase." } } } }, "next": { "type": "string" } } }, "PurchaseRequest": { "type": "object", "required": [ "purchaseToken", "email", "idempotencyKey" ], "properties": { "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." }, "email": { "type": "string", "format": "email", "description": "Shopper email for order confirmation and shipping updates." }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 128, "description": "Client-generated unique key (UUID recommended). Retrying with the same key never creates a second order." }, "phone": { "type": "string", "maxLength": 30 } } }, "PurchaseResponse": { "type": "object", "required": [ "ok", "status", "ref", "order", "payment" ], "properties": { "ok": { "type": "boolean" }, "status": { "type": "string", "enum": [ "completed" ] }, "ref": { "type": "string", "description": "Butiful purchase reference (BAX-...). Also written on the Shopify order." }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "Shopify order number, e.g. #1234." } } }, "payment": { "type": "object", "properties": { "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "amountUsd": { "type": "string" }, "payer": { "type": "string" }, "transaction": { "type": "string", "nullable": true } } }, "shipping": { "type": "object", "properties": { "method": { "type": "string" }, "destinationCountry": { "type": "string" } } }, "receipt": { "type": "object", "nullable": true, "properties": { "token": { "type": "string" }, "statusUrl": { "type": "string" } } }, "message": { "type": "string" }, "replay": { "type": "boolean", "description": "true when this response is an idempotent replay of an earlier completed purchase." } } }, "OrderStatusResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "ref": { "type": "string" }, "status": { "type": "string", "description": "Ledger status: pending, draft_created, settled, completed, settle_failed, settle_unknown, complete_failed, rejected." }, "order": { "type": "object", "nullable": true, "properties": { "name": { "type": "string" }, "createdAt": { "type": "string" }, "financialStatus": { "type": "string" }, "fulfillmentStatus": { "type": "string" }, "cancelled": { "type": "boolean" }, "closed": { "type": "boolean" } } }, "fulfillments": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "updatedAt": { "type": "string" }, "tracking": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string" }, "url": { "type": "string" }, "company": { "type": "string" } } } } } } }, "payment": { "type": "object" }, "shippingMethod": { "type": "string", "nullable": true } } }, "PaymentRequiredResponse": { "type": "object", "required": [ "x402Version", "accepts", "resource" ], "properties": { "x402Version": { "type": "integer", "enum": [ 2 ] }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" } } }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string", "enum": [ "exact" ] }, "network": { "type": "string", "description": "CAIP-2 network id, e.g. eip155:8453 (Base)." }, "amount": { "type": "string", "description": "Atomic USDC units (6 decimals): \"20400000\" = 20.40 USD." }, "asset": { "type": "string", "description": "USDC contract address on the network." }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer" }, "extra": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "assetTransferMethod": { "type": "string" } } } } } }, "extensions": { "type": "object" } } }, "ErrorResponse": { "type": "object", "required": [ "ok", "error", "message" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string" }, "ref": { "type": "string", "description": "Purchase ledger reference (BAX-...) when one exists." } } } } } }