Skip to main content
POST
/
v1
/
tools
/
commerce
/
buy
Buy Product
curl --request POST \
  --url https://api.example.com/v1/tools/commerce/buy \
  --header 'Content-Type: application/json' \
  --data '
{
  "product_url": "<string>",
  "shipping_address": {
    "first_name": "<string>",
    "last_name": "<string>",
    "street": "<string>",
    "street2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "zip_code": "<string>",
    "country": "<string>",
    "phone": "<string>",
    "email": "<string>"
  },
  "quantity": 123,
  "variant_id": "<string>"
}
'

​
Overview

Purchase products from Amazon, Shopify stores, and other supported retailers. Uses a quote-to-pay flow:
  1. First call returns a 402 with quote details and quote_id
  2. Second call with X-Quote-ID and X-Payment headers executes the purchase

​
Request Body

​
product_url
string
required
URL of the product to purchase (Amazon, Shopify, etc.)
​
shipping_address
object
required
Shipping address for delivery
​
quantity
number
default:1
Quantity to purchase
​
variant_id
string
Specific product variant ID (if applicable)

​
Response (402 - Quote)

First call returns quote details: 
{
  "error": "payment_required",
  "context": {
    "quote_id": "quote_abc123",
    "product_title": "Wireless Headphones",
    "subtotal": "79.99",
    "shipping": "5.99",
    "tax": "7.20",
    "fee": "2.50",
    "total": "95.68"
  },
  "payment_request": {
    "chain_id": 8453,
    "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "95.68",
    "recipient": "0x..."
  }
}

​
Response (202 - Order Submitted)

Second call with payment returns: 
{
  "request_id": "req_xyz789",
  "status": "processing",
  "message": "Order submitted successfully"
}

​
Job Result

{
  "status": "completed",
  "result": {
    "status": "order_submitted",
    "order_id": "114-1234567-8901234",
    "order_status": "placed",
    "tracking_url": "https://...",
    "provider": "amazon"
  }
}

​
SDK Usage

const order = await agent.commerceBuy({
  product_url: "https://amazon.com/dp/B07ZPC9QD4",
  shipping_address: {
    first_name: "John",
    last_name: "Doe",
    street: "123 Main St",
    city: "San Francisco",
    state: "CA",
    zip_code: "94102",
    country: "US",
    phone: "4155550100",
  },
  quantity: 1,
  maxCost: 100, // Optional: fail if total exceeds this
});

console.log(`Order ID: ${order.order_id}`);
console.log(`Status: ${order.order_status}`);
console.log(`Tracking: ${order.tracking_url}`);

​
Limitations

Only US shipping addresses are currently supported. Requests with non-US country codes will return a 400 error.

​
Supported Retailers

  • Amazon (US)
  • Shopify stores
  • Many more US-based retailers