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

# Search Products

> Search for products across supported retailers

## Overview

Search for products across Amazon, Shopify, and other supported retailers. Returns product information including prices, availability, and purchase URLs.

## Request Body

<ParamField body="query" type="string" required>
  Search query (e.g., "wireless bluetooth headphones")
</ParamField>

<ParamField body="limit" type="number" default={10}>
  Maximum number of results to return (max: 50)
</ParamField>

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

## Response (202 - Processing)

```json theme={null}
{
  "request_id": "req_abc123",
  "status": "processing",
  "tool": "commerce_search",
  "message": "Search job queued successfully"
}
```

## Job Result

Poll `/v1/requests/{request_id}` for results:

```json theme={null}
{
  "status": "completed",
  "result": {
    "status": "success",
    "query": "wireless bluetooth headphones",
    "products": [
      {
        "product_url": "https://amazon.com/dp/B09XS7JWHH",
        "title": "Sony WH-1000XM5 Wireless Headphones",
        "price": 348.00,
        "currency": "USD",
        "image_url": "https://...",
        "vendor": "Sony",
        "rating": 4.7,
        "review_count": 12500,
        "in_stock": true,
        "description": "Industry-leading noise canceling..."
      }
    ],
    "count": 10
  }
}
```

## SDK Usage

```typescript theme={null}
const results = await agent.commerceSearch({
  query: "wireless bluetooth headphones",
  limit: 10,
});

for (const product of results.products) {
  console.log(`${product.title}: $${product.price}`);
  console.log(`  URL: ${product.product_url}`);
}
```

## Example: Search and Buy Flow

```typescript theme={null}
// 1. Search for products
const search = await agent.commerceSearch({
  query: "USB-C hub",
  limit: 5,
});

// 2. Pick the best result
const bestProduct = search.products[0];

// 3. Purchase it
const order = await agent.commerceBuy({
  product_url: bestProduct.url,
  shipping_address: {
    first_name: "John",
    last_name: "Doe",
    street: "123 Main St",
    city: "San Francisco",
    state: "CA",
    zip_code: "94102",
    phone: "4155550100",
  },
});
```