> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Buy Product

> Purchase a product from supported retailers

## 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

<ParamField body="product_url" type="string" required>
  URL of the product to purchase (Amazon, Shopify, etc.)
</ParamField>

<ParamField body="shipping_address" type="object" required>
  Shipping address for delivery

  <Expandable title="properties">
    <ParamField body="first_name" type="string" required>First name</ParamField>
    <ParamField body="last_name" type="string" required>Last name</ParamField>
    <ParamField body="street" type="string" required>Street address</ParamField>
    <ParamField body="street2" type="string">Apartment, suite, etc.</ParamField>
    <ParamField body="city" type="string" required>City</ParamField>
    <ParamField body="state" type="string" required>State/Province code</ParamField>
    <ParamField body="zip_code" type="string" required>ZIP/Postal code</ParamField>
    <ParamField body="country" type="string">Country code. Must be `US` — only US shipping is currently supported.</ParamField>
    <ParamField body="phone" type="string" required>Phone number</ParamField>
    <ParamField body="email" type="string">Email for order updates</ParamField>
  </Expandable>
</ParamField>

<ParamField body="quantity" type="number" default={1}>
  Quantity to purchase
</ParamField>

<ParamField body="variant_id" type="string">
  Specific product variant ID (if applicable)
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Response (402 - Quote)

First call returns quote details:

```json theme={null}
{
  "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:

```json theme={null}
{
  "request_id": "req_xyz789",
  "status": "processing",
  "message": "Order submitted successfully"
}
```

## Job Result

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

## SDK Usage

```typescript theme={null}
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

<Warning>
  Only **US shipping addresses** are currently supported. Requests with non-US
  `country` codes will return a `400` error.
</Warning>

## Supported Retailers

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