Shopping HTTP quickstart

Request integration access

Contact Relay with your application, the tasks your users bring to it and the first connector you need. Access is provisioned for the approved integration. Set RELAY_BASE_URL to the service origin supplied for your integration and keep RELAY_API_TOKEN in your server's secret store.

Never include credentials in browser code, prompts, query strings or logs. Relay's website is not the API service origin.

Search for products

Send a product query and the constraints relevant to that request. Prices use integer minor currency units: 15000 with USD means $150.00.

curl --request POST "$RELAY_BASE_URL/v1/tools/search_products" \
  --header "Authorization: Bearer $RELAY_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"query":"travel backpack","max_price":15000,"currency":"USD","limit":3,"context":{"platform":"api","region":"US"}}'

Inspect organic_results, promoted_results, sources and fetched_at. A successful HTTP response can include a failed source or no matching inventory. Keep promoted inventory separate and disclosed. Stock, delivery and prices that are missing remain unknown.

Compare products and offers

Use compare_products with two to five product_ids. Products and merchant offers have separate identities. For the chosen product, call get_offers and select the specific offer_id, variant, condition and merchant.

{
  "product_id": "PRODUCT_ID_FROM_SEARCH",
  "context": {"platform": "api", "region": "US"}
}

Send this body to POST /v1/tools/get_offers. Do not compare unlike variants, currencies or conditions as equivalent offers. Shipping that is unknown is not free shipping. Preserve the original observation times for cached results.

Prepare the assistant handoff

Use get_purchase_link with the selected product and offer, expected price, selected options, quantity and an idempotency key. The following IDs and price are illustrative placeholders to replace with the actual selection.

{
  "product_id": "PRODUCT_ID_FROM_SEARCH",
  "offer_id": "OFFER_ID_FROM_GET_OFFERS",
  "selected_options": {"Color": "Blue"},
  "quantity": 1,
  "expected_price": {"amount": 12900, "currency": "USD"},
  "purchase_mode": "browser_handoff",
  "idempotency_key": "example_handoff_0001",
  "context": {"platform": "api", "region": "US"}
}

Send this body to POST /v1/tools/get_purchase_link. Reuse the idempotency key only for retries of the same intended handoff. A changed selection requires a new key. If the price or offer changes, review the current offer before continuing.

Return the prepared selection and destination to your assistant. Preserve the destination URL bytes exactly, including attribution. The assistant retains its own tools, approvals and final action. Verify the current offer, shipping, tax, stock and selected options before completing a purchase. A prepared handoff is not a completed purchase.

Handle incomplete results and errors

• Read source status when results are partial or empty.
• Correct invalid fields before retrying a 400 response.
• Resolve authentication, scope or policy denials for 401 and 403 responses.
• Review changed prices or selections for a 409 response.
• Respect rate and capacity limits, Retry-After and bounded retry guidance for 429 and 503 responses.
• A failed refresh does not validate the old price or stock.

Continue with the full references

Shopping's complete tools, inputs and handoff behavior remain in the Shopping connector reference. Use the AI assistant integration guide for MCP authentication, independent connector installation, scopes, shared context, provider access and journeys. The provider guide and platform architecture cover the broader integration.

This HTTP example does not require a released Relay SDK. It does not provision credentials or make a provider request from this documentation page.