# Butiful Agent Commerce – Purchase

> Butiful Agent Commerce – Purchase is a paid API for AI agents from agent.butiful.org, paid per call via x402, $0.01/call, status unknown (last checked 2026-09-15).

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.

## Facts

- Endpoint: POST https://agent.butiful.org/api/agent/purchase
- Price: $0.01/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/butiful-agent-commerce-purchase-acc2eec0
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_O4e_LdvNFMiu74wWVdbsU

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability butiful-agent-commerce-purchase-acc2eec0 -d '<json body>'
```

Example prompt: 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.

## When to prefer this

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.

## Known failure modes

- 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

## How this service works

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.

## Output

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.

## Request schema (JSON Schema)

```json
{
 "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."
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "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"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/butiful-agent-commerce-purchase-acc2eec0/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agent.butiful.org](https://www.zero.xyz/host/agent.butiful.org/llms.txt)