# Butiful Agent Commerce

> 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. Butiful (https://www.butiful.org) is a women's fashion boutique run by BUTIFUL L.L.C.

## Flow
1. GET https://agent.butiful.org/api/agent/catalog?q=<search>  (free) - products, variants, prices, availability, images. Keep each variant's `variantId`.
2. POST https://agent.butiful.org/api/agent/quote  (free) - body { items:[{variantId, quantity}], shippingAddress:{...}, email? }. Returns Shopify's real shipping options with tax and the exact total per option, each with a signed `purchaseToken` (valid 15 min).
3. POST https://agent.butiful.org/api/agent/purchase - body { purchaseToken, email, idempotencyKey }. Without PAYMENT-SIGNATURE it returns HTTP 402 with the exact amount for that token. Pay it with x402 v2 (scheme "exact", USDC on Base, eip155:8453, amount in atomic units = USD x 1,000,000) and retry with PAYMENT-SIGNATURE.
4. GET https://agent.butiful.org/api/agent/orders/{ref}?receipt=<token> - order, fulfillment and tracking status.

## Guarantees
- Payment is verified before any order exists and settled only after Shopify has accepted the basket; any failure before settlement charges nothing.
- The same idempotencyKey never creates a second order; a replay returns the original result.
- If the store total changes between quote and purchase you get 409 quote_stale and nothing is charged - request a new quote.
- Prices, inventory, shipping rates and tax come from Shopify at request time; this API holds no separate catalog.
- Orders above 1000 USD, returns, exchanges and refunds go through the store's normal customer channels. USDC refunds are handled manually by the store.

## Discovery
- OpenAPI: https://agent.butiful.org/openapi.json
- Status and payment terms: https://agent.butiful.org/api/agent/status
- Contact: butifulstore1@gmail.com