Search Products
Search retail product catalogs (Amazon or Walmart) by keyword. Returns matching products with title, brand, image, price in USD, star rating, review count, and availability; each result includes a product URL that feeds directly into get-product-details and order-product. By default returns ONLY orderable products (the top hits are verified to be purchasable via checkout, so Amazon Fresh / grocery / perishable produce and unavailable listings are filtered out even when they still advertise a catalog price); pass orderableOnly=false for raw catalog results. Also filters to free-shipping items by default (Amazon Prime / Walmart $0 shipping) so results are quote-safe; pass freeShipping=false to include paid-shipping listings. Ideal for: finding physical products to order, price comparison, building shopping workflows.
Catalog action Integrations
Search retail product catalogs (Amazon or Walmart) by keyword. Returns matching products with title, brand, image, price in USD, star rating, review count, and availability; each result includes a product URL that feeds directly into get-product-details and order-product. By default returns ONLY orderable products (the top hits are verified to be purchasable via checkout, so Amazon Fresh / grocery / perishable produce and unavailable listings are filtered out even when they still advertise a catalog price); pass orderableOnly=false for raw catalog results. Also filters to free-shipping items by default (Amazon Prime / Walmart $0 shipping) so results are quote-safe; pass freeShipping=false to include paid-shipping listings. Ideal for: finding physical products to order, price comparison, building shopping workflows.
At a Glance
| Field | Value |
|---|---|
| Action ID | search-products |
| Category | Integrations |
| Connector | Not required |
| Requires gas | No |
| Funds movement | None declared |
| Tags | shopping, products, search, ecommerce, read |
Payload Schema
| Field | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search keywords describing the product (e.g. 'wireless mouse', 'coffee grinder'). |
retailer | string | No | Retailer catalog to search. Default: 'amazon'. |
page | number | No | Result page number (1-based). Default: 1. |
orderableOnly | boolean | No | Return ONLY products that can actually be ordered (default: true). When true, the top results are verified to have a purchasable price, so non-orderable listings (Amazon Fresh / Whole Foods grocery, perishables with no buy-box price) are dropped before they reach the user. Set false for raw catalog results. |
freeShipping | boolean | No | Return ONLY items that ship for free (default: true). On Amazon this means Prime-eligible items; on Walmart, items with $0 shipping. The retailer applies this server-side, so Prime is filtered accurately (the per-result 'prime' flag is logged-out and under-reports). Set false to include paid-shipping listings. |
Result Schema
| Field | Type | Required | Description |
|---|---|---|---|
results | array | Yes | Matching products, in retailer ranking order. |
retailer | string | Yes | Retailer that was searched. |
query | string | Yes | The search query used. |
Examples
json{ "type": "search-products", "payload": { "query": "status:open" }, "children": []}
bashcurl -X POST "https://api.b3os.org/v1/actions/search-products/test" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "inputs": { "query": "status:open" }}'
Payload fields can use workflow expressions such as {{$trigger.body.amount}}, {{$nodes.fetch.result.price}}, and {{$props.asset}} when the value should come from a trigger, prior node, or reusable workflow prop.