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

# Product Search

> Search for products across supported retailers

<img src="https://mintcdn.com/freebutter/4_BNr2wKOFDNd9xk/images/features/commerce.webp?fit=max&auto=format&n=4_BNr2wKOFDNd9xk&q=85&s=bb22e1300408e450bc3d44ecece80aad" alt="" className="docs-object" noZoom width="1200" height="600" data-path="images/features/commerce.webp" />

## Overview

Searches Amazon, Shopify, and other supported retailers and returns products with price, availability, and purchase URL. The search runs as a job: you get a `request_id`, then poll `/v1/requests/{request_id}` for the result (the search runs in the API, so it is usually there on the first poll). Pass a result's `product_url` to [Purchase](/api-reference/commerce/buy).

## Request Body

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

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

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

## Response (202 - Processing)

```json theme={null}
{
  "request_id": "req_abc123",
  "receipt_id": "rcpt_abc123",
  "status": "processing",
  "tool": "commerce",
  "message": "Product search in progress. Check status with /v1/requests/{id}."
}
```

## Job Result

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

```json theme={null}
{
  "request_id": "req_abc123",
  "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": null,
        "vendor": "Amazon",
        "rating": null,
        "review_count": null,
        "in_stock": null,
        "description": "Industry-leading noise canceling..."
      }
    ],
    "count": 1
  }
}
```

`price`, `image_url`, `vendor`, `rating`, `review_count`, `in_stock` and `description` are `null` when the search did not find them. A search that finds nothing completes with `products: []` and `count: 0`. A search that could not run ends the job `failed` with an `error_code`.

## SDK Usage

```typescript theme={null}
const results = await agent.productFind({
  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.productFind({
  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.product_url,
  shipping_address: {
    first_name: "John",
    last_name: "Doe",
    street: "123 Main St",
    city: "San Francisco",
    state: "CA",
    zip_code: "94102",
    phone: "4155550100",
  },
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.