Commerce and markets · SearchApi

shopping.search

Searches structured product listings with source prices and merchant links. Returned filters have session-owned ids: use update with filter_id to select, or null to clear. Query/localization changes clear the selection; filter choices cannot combine with sort or condition. Explicit price bounds remain enforced. Details use the provider product token; unavailable or expired offers remain unavailable, never estimated.

Operation: POST /v1/capabilities/shopping.search/execute
operationId: executeShoppingSearch
Typical credits: 4
Search deadline: 40 s server-side
Paging: page
Availability: ConfiguredChecked 2026-09-23 21:02 UTC

Cost basis: $0.004 per provider page or fresh product detail. Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request

Body of POST /v1/capabilities/shopping.search/execute, JSON, validated against the ShoppingSearchRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of shopping.search
Field	Type	Required	Default	Constraints and description
query	string	yes		min length 1, max length 500
country	string	no		pattern ^[a-zA-Z]{2}$ Search country code; prices use this market’s currency.
language	string	no		min length 2, max length 12
location	string	no		min length 1, max length 200
filter_id	string \| null	no		For follow-up update only: choose a filter id returned by this search; null clears the selection. Query/localization changes clear it. Cannot combine with sort or condition.
num	integer	no	10	min 1, max 25
price_min	number	no		min 0, max 100000000 Minimum item price in the selected country’s currency, excluding delivery.
price_max	number	no		min 0, max 100000000 Maximum item price in the selected country’s currency, excluding delivery.
condition	"new" \| "used"	no
sort	"price_low_to_high" \| "price_high_to_low" \| "rating_high_to_low"	no

Unknown keys are rejected with 400 invalid_request.

Rules the schema cannot express

Checked after schema validation; violations return 400 invalid_request with a plain message.

price_min must not exceed price_max.
filter_id is accepted only on update, must come from this search, and cannot be combined with sort or condition.

Examples

Products

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/shopping.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"noise cancelling headphones","num":5}'

No recorded response is published for this capability yet. The envelope is the ExecuteResponse component (see sessions and records); the record keys below are what the adapter emits. A first call with the example above returns search_id, the records and the charge.

Result record

Every item in results[] carries record_id and title (contract, always present) and usually url and snippet. The keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the ShoppingSearchRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. See stability tiers.

Record keys of shopping.search
Key	Type	Presence
price	number	when the source has it
price_display	string	when the source has it
seller	string	when the source has it
rating	number	when the source has it
reviews	integer	when the source has it
delivery	string	when the source has it
condition	string	when the source has it
source	string	always

Caveats

The execute envelope carries filters[] (id, label, group) for use with update.

Follow-ups

Paging: Provider page number; more fetches the next page from the source. Send { "search_id": "…", "action": "more" } while has_more is true; tolerate an empty page and stop after a bounded number of pages.
Update: Re-run with changed parameters (merged into the stored query); page state resets, search_id stays. Params accept any subset of the request fields (ShoppingSearchUpdateParams). Changing query, country, language or location clears any filter_id; sending a filter_id together with such a change is refused. Choose filters from the filters[] of the current search only.
Record actions:
- details: Product specifications and source merchant offers.
Detail behaviour: First details call fetches from the provider (billed as stated); repeats are cached and free. details is a fresh product request: $0.004; repeated calls are cached.

record action

curl -s -X POST https://api.powerups-ai.store/v1/follow-up \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id":"rec_…","action":"details"}'

Record detail objects of this capability are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

TypeScript (openapi-fetch)

const { data, error } = await client.POST("/v1/capabilities/shopping.search/execute", {
  body: {
    "query": "noise cancelling headphones",
    "num": 5
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);