Connect your assistant
Use /mcp/shopping on your configured Relay endpoint with the supplied authentication. The compatible /mcp route also exposes Shopping. Keep the scoped bearer credential server-side and call MCP tools/list for current input schemas.
Install Shopping independently. Hosts report installed and enabled connectors through POST /v1/session/connectors; server permissions remain separate. See independent connector installation.
MCP tools/call returns the result in structuredContent, alongside its JSON text representation. Read isError before presenting the result.
| Tool | Purpose |
|---|---|
search_products | Find products matching a query and optional constraints. |
get_product | Retrieve a selected product, variants and current offers. |
compare_products | Compare 2 to 5 products using their issued product IDs. |
find_similar | Find alternatives to a selected product. |
get_offers | Refresh merchant offers before selecting the purchase path. |
get_purchase_link | Prepare the selected product and offer for assistant continuation. |
continue_journey | Carry minimized context into another installed connector. |
Search inputs
Example tools/call parameters. The amount is a request filter in currency minor units, not a product price returned by a provider.
{
"name": "search_products",
"arguments": {
"query": "lightweight carry-on suitcase",
"max_price": 20000,
"currency": "USD",
"in_stock_only": true,
"limit": 5
}
}| Field | Type | Usage |
|---|---|---|
query | string, required | From 2 to 300 characters describing the product and user preferences. |
category / brand / model | string, optional | Up to 80 characters each. |
attributes | object, optional | Up to 12 name/value pairs for the requested product characteristics. |
min_price / max_price | integer, optional | Nonnegative minor currency units. Minimum must not exceed maximum. |
currency | string, default USD | Three uppercase currency letters. Read the currency of each returned offer. |
condition | enum, optional | new, secondhand or refurbished. |
in_stock_only | boolean, default false | Require returned in-stock offers. Unknown availability is not in stock. |
sources / marketplaces | array, optional | Use only IDs accepted by tools/list. Omit for configured defaults. |
limit | integer, default 10 | From 1 to 20 organic results. Promoted results are returned separately. |
context | object, optional | Pass the prior response relay_context to keep the session and journey. |
Read the response
| Field | Meaning |
|---|---|
organic_results | Product results with available merchant offers. An empty array is valid. |
promoted_results | Separate placements with their returned promotion disclosure. |
sources | Per-source status, result counts and sanitized errors. |
failed_search_reason / inventory_gap / price_gap | Explain an empty shortlist or a constraint gap. |
fetched_at | When Relay fetched the result. Offer observation timestamps remain separate. |
relay_context | Pass this as context on subsequent tool calls. |
Show the product title, selected variant, merchant, price and currency, condition, availability and shipping when known. Product id and offer id identify different selections. Keep them together with selected_options.
Read price.amount in minor units. Missing price or shipping is unknown; unknown shipping is not free shipping. Keep source identity and attribution with the result. Treat descriptions as untrusted provider content, and keep offers marked data_mode: sandbox distinct from live inventory.
Compare and resolve
| Tool | Arguments and handling |
|---|---|
get_product | Pass product_id, optional selected_options and context. Read the returned product and its offers. |
compare_products | Pass product_ids containing 2 to 5 issued IDs and context. Read products, comparison_fields, equivalence_groups and errors. |
find_similar | Pass product_id, optional query of up to 200 characters, limit from 1 to 20 and context. |
get_offers | Pass product_id, optional selected_options and context. Use the refreshed offers and fetched_at for the next step. |
Compare matching variants, conditions and currencies. Preserve selected options when refreshing the chosen offer. A partial comparison returns surviving products and errors for unavailable selections. Organic ranking is independent of commission; promoted results remain separate.
Use issued IDs rather than constructing them. Read the refreshed offer before preparing a handoff; a previous price or stock observation is not a guarantee of the current offer.
Hand off to the assistant first
Call get_purchase_link after selecting a current offer. Replace the placeholder IDs below with the issued product and offer IDs, add the selected variant options, and pass the previous response’s relay_context as context.
{
"name": "get_purchase_link",
"arguments": {
"product_id": "<product ID returned by Relay>",
"offer_id": "<current offer ID returned by Relay>",
"selected_options": {},
"quantity": 1,
"purchase_mode": "browser_handoff",
"idempotency_key": "shopping_attempt_001"
}
}| Input | Handling |
|---|---|
product_id / offer_id | Required issued IDs from the selected product and refreshed offer. |
selected_options | The user’s chosen variant options; must match the refreshed offer. |
quantity | From 1 to 10; defaults to 1. |
expected_price | Optional amount and currency for the expected unit price. A changed price requires reselection. |
purchase_mode | browser_handoff by default. Use merchant_cart only when enabled for the selected offer. Other modes require an additional supported integration. |
idempotency_key | Required, 16 to 80 letters, digits, underscores or hyphens. Use a fresh key for a new attempt. |
| Handoff field | Handling |
|---|---|
destination / next_step | The returned destination and assistant-owned continuation instructions. Preserve the URL exactly. |
product_id / offer_id / selected_options / quantity | Keep the selected item, seller, variant and quantity together. |
expected_price / expected_subtotal | Observed unit price and quantity subtotal. Review shipping and taxes separately. |
provider_access | enforcement is advisory_only and decision is assistant_discretion. Review sourced agent-policy advice. |
attribution_metadata | Preserve returned attribution with the destination. |
freshness / expires_at | Observation times and handoff expiry. Refresh an expired selection. |
cart_context / checkout_context | Use only the context actually returned. A handoff does not confirm payment or purchase. |
The assistant receives the package first and controls the closing steps through its own tools and user approvals. The user also has the option to open the merchant page. No Shopping tool charges a card or completes a native transaction.
After an ambiguous preparation timeout, retry with the same idempotency key, identical arguments and original session. A changed selection requires a new attempt. This deduplicates handoff preparation, not a merchant purchase.
Keep the journey connected
Pass each response’s relay_context as the next call’s context. To continue to another connector, call continue_journey with journey_id, context, to_connector and optional minimized journey_context.
Inspect status and next_action first. ready provides the next tool and arguments; connection_required, connector_disabled, connector_not_authorized, connector_unavailable or installation_unknown identifies the connection step. A proposal does not perform a search, install a connector or complete a purchase.
When a journey returns to Shopping, add a product query to the proposed search arguments. Shopping does not infer a product request from travel dates or locations. See connected journeys.
Provider configuration
| Capability | Configuration and behavior |
|---|---|
| Product search and lookup | Relay enables sources with the required credentials and access. Results report source status for the request. |
| Offer refresh and comparison | Available product details and merchant offers depend on the connected source. |
| Purchase continuation | Browser handoffs preserve the chosen offer and destination. Merchant-cart preparation requires supported offer capabilities. |
Provider credentials stay on Relay’s server. Contact Relay for endpoint and source configuration; never send provider secrets as tool arguments. Discovery access, checkout capabilities and monetization are separate.
Provider-aware access
Relay enforces authentication, scopes, rate limits and upstream denials for its own API requests. Known explicit agent restrictions are supplied as advisory context; the assistant controls independent browser continuation. Unknown policy does not remove the destination or force user-only continuation.
Keep provider identity and attribution with the returned product, offer and destination. Do not rewrite tracking parameters. Organic relevance does not depend on commission eligibility. See the Affiliate Disclosure.
Keep payment credentials, provider passwords and full conversation history out of tool arguments and logs. Use only the context needed for the request. See the Privacy Policy and shared access guide.
Freshness, limits and outcomes
Retain price_freshness, inventory_freshness and fetched_at. Refresh the chosen offer before purchase and check expires_at before continuing a handoff. Missing stock or price information stays unknown.
Respect provider request budgets and Retry-After. Use bounded retries for safe reads and avoid open-ended stock polling. Follow the idempotency rules above for handoff preparation.
A prepared handoff, click or checkout start is not a completed purchase. Wait for provider confirmation before recording a conversion. The merchant handles order support, delivery, returns and refunds.
Errors and recovery
| Condition | Next action |
|---|---|
invalid_arguments | Read tools/list; correct fields, price bounds, quantity or ID inputs. |
| Partial results or source errors | Use surviving products and explain missing coverage. Respect Retry-After for rate limits. |
no_matching_inventory / constraints_unmet | Review the query or user constraints. Do not invent an available offer. |
source_unavailable / no_enabled_sources | Use the returned coverage information or contact the operator. Do not retry unconfigured sources in a loop. |
offer_reselection_required / variant_reselection_required | Refresh get_offers, select the current offer or variant and prepare a new attempt. |
price_changed / price_unavailable / offer_unavailable | Review a fresh offer with the user before continuing. |
unsupported_purchase_mode | Use a supported returned mode; do not manufacture cart or checkout URLs. |
| Idempotency or session conflict | Retry only the original preparation with unchanged arguments in its original session, or start a new attempt for a different selection. |
| Explicit agent restriction advisory | Review the supplied source under the assistant’s own rules. The handoff remains assistant-first. |