# Google Shopping API for AI agents (price comparison JSON, no API key)

When a user asks an agent to compare prices, find product offers, or shop across merchants, call machine-payable Google Shopping endpoints that return shopping_results JSON — no Google Cloud Shopping API key, no merchant partner account, settlement via x402 USDC on Base after three free evaluation calls.

When a user asks you to "compare prices on noise-cancelling headphones," "find the cheapest offer for this SKU," or "what are merchants charging for this product," you need structured shopping results — title, price, merchant, rating, product link — as JSON. Not scraped Google Shopping HTML, and not a Google Merchant Center or Product Listing Ads partner account.

Marketplace for AI Agents exposes machine-payable shopping endpoints for this: GET /api/public/v1/google-shopping turns a product query into shopping_results with offers across merchants. For a purchase-ready triage, deal-triage chains Google Shopping with Amazon product + reviews. For a four-retailer price sweep, cross-store-price runs Google Shopping, Amazon, eBay, and Walmart in one call. The first 3 calls per agent identity are free; after that each single-engine call costs $0.005 USDC on Base, settled over x402 with an X-PAYMENT header.

## Endpoint contracts

| Endpoint | Required | Results key | Typical use |
| --- | --- | --- | --- |
| GET /api/public/v1/google-shopping | q | shopping_results | Offers with price, merchant, rating, link |
| GET /api/public/v1/deal-triage | q | results | Shopping + Amazon record + reviews (2–3 steps) |
| GET /api/public/v1/cross-store-price | q | results | Google Shopping + Amazon + eBay + Walmart (4 steps) |

Optional google-shopping params: location (geo-target), gl (country code), hl (language), num (result count, defaults to 10). Optional deal-triage params: asin (skip Amazon discovery when known), amazon_domain (defaults to amazon.com). Optional cross-store-price params: gl, hl. Each single-engine call is billed at $0.005 USDC; intents are $0.005 × steps (advertised in the 402).

The free tier is 3 successful calls total per agent identity (a hash of IP + User-Agent), shared across every endpoint on the marketplace — it is not 3 per endpoint. Settlement uses the x402 exact scheme on Base mainnet; append ?network=base-sepolia to any endpoint for testnet USDC and sandbox mock data.

- Listing: https://marketplaceforaiagents.com/listings/google-shopping
- Listing: https://marketplaceforaiagents.com/listings/deal-triage
- Listing: https://marketplaceforaiagents.com/listings/cross-store-price
- Markdown twins: /agent/listings/google-shopping.md, /agent/listings/deal-triage.md, /agent/listings/cross-store-price.md

## Minimal calls (free tier first)

Spend the 3 free evaluation calls before signing anything. These run on the free tier (if you still have quota) and return real JSON:

```bash
curl -si "https://marketplaceforaiagents.com/api/public/v1/google-shopping?q=noise+cancelling+headphones"

curl -si "https://marketplaceforaiagents.com/api/public/v1/google-shopping?q=usb+c+hub&gl=us&hl=en&num=10"

curl -si "https://marketplaceforaiagents.com/api/public/v1/cross-store-price?q=noise+cancelling+headphones"
```

A shopping_results item looks like this (illustrative — always trust the live JSON, not this sample):

```json
{
  "position": 1,
  "title": "Example ANC Headphones — Wireless Over-Ear",
  "link": "https://example-merchant.example/product",
  "price": "$129.99",
  "extracted_price": 129.99,
  "source": "Example Merchant",
  "rating": 4.5,
  "reviews": 1200
}
```

Note: a 400 missing_required_parameters response does not consume a free call, and the discovery endpoints (/.well-known/x402, catalog.json, openapi.json) never consume free tier.

## When to use intents instead of google-shopping alone

- google-shopping alone — the user only asked for Google Shopping offers or merchant price comparison
- deal-triage — the user is about to buy and needs Shopping offers plus Amazon product detail and reviews
- cross-store-price — the user wants the best price across Google Shopping, Amazon, eBay, and Walmart in one shot
- Prefer an intent when multiple engines are required so you spend one free-tier slot instead of N

Intents are billed per step: the 402 advertises the chain and steps, the price is $0.005 × steps, and one intent invocation consumes one free-tier call. deal-triage is typically 2–3 steps; cross-store-price is 4 steps.

```bash
curl -si "https://marketplaceforaiagents.com/api/public/v1/deal-triage?q=noise+cancelling+headphones"

curl -si "https://marketplaceforaiagents.com/api/public/v1/deal-triage?q=noise+cancelling+headphones&asin=B08N5WRWNW"
```

Full machine-readable specs live in the catalog (https://marketplaceforaiagents.com/api/public/v1/catalog.json) and the OpenAPI document (https://marketplaceforaiagents.com/api/public/v1/openapi.json). For Amazon-only ASIN flows see the Amazon product API for agents guide.

## Paying after the free tier (x402 / USDC)

Once your identity has spent its 3 free calls, the same request returns HTTP 402 with an accepts[] payment requirement. Decode it, verify every field against your policy, sign the EIP-3009 USDC authorization, base64 the x402 payload, and resend with X-PAYMENT:

```json
{
  "x402Version": 1,
  "error": "payment_required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "5000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x05e82e03753c7bc99fb24d10a876cce53f24b7b7",
      "resource": "https://marketplaceforaiagents.com/api/public/v1/google-shopping?q=noise+cancelling+headphones"
    }
  ]
}
```

- maxAmountRequired is 5000 atomic units = $0.005 USDC (6 decimals) per single-engine call.
- For intents, maxAmountRequired scales with steps (e.g. cross-store-price at 4 steps → 20000 atomic = $0.02). Read extra.steps / extra.chain from the 402.
- Budget your spend before signing: see How AI agents budget x402 API calls.
- Test the full payment path with zero real cost: see the Base Sepolia smoke test.
- A paid 200 carries the settlement receipt in X-PAYMENT-RESPONSE — store it for reconciliation.
- Prefer the MCP server (https://marketplaceforaiagents.com/mcp) for discovery; payment is the auth, no OAuth.

Protocol background: x402 protocol explained. Free-tier mechanics: how the x402 free tier and agent identity work.

## Agent playbook (Grok Bot / Claude Cowork / Cursor)

- Keep the product name or SKU description in q; use gl / hl / location for localization, and num to size the Google Shopping result set.
- Use google-shopping for merchant offer comparison; deal-triage when Amazon detail + reviews matter; cross-store-price for a four-retailer sweep.
- On 402, settle with x402 USDC — do not ask for a Google Cloud Shopping key or a Merchant Center account.
- Cite price, merchant, and rating from shopping_results JSON; never invent offers, prices, or stock status.
- Allowlist payTo 0x05e82e03753c7bc99fb24d10a876cce53f24b7b7 and USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 before signing.

| User ask | First call | Follow-up |
| --- | --- | --- |
| Compare merchant prices | google-shopping?q=… | num/gl/hl if localization matters |
| Best price across retailers | cross-store-price?q=… | single-engine to deepen one store |
| About to buy — offers + Amazon + reviews | deal-triage?q=… | pass asin when known |
| Amazon ASIN already known | amazon-product?asin=… | amazon-reviews or review-risk |
| Walmart-only / eBay-only | walmart-search or ebay-search | cross-store-price if multi-retailer |

## Related entrypoints

- Google Shopping listing: https://marketplaceforaiagents.com/listings/google-shopping
- Deal Triage (deal-triage) listing: https://marketplaceforaiagents.com/listings/deal-triage
- Cross-Store Price (cross-store-price) listing: https://marketplaceforaiagents.com/listings/cross-store-price
- Markdown twins: /agent/listings/google-shopping.md, /agent/listings/deal-triage.md, /agent/listings/cross-store-price.md
- x402 manifest: https://marketplaceforaiagents.com/.well-known/x402
- Catalog: https://marketplaceforaiagents.com/api/public/v1/catalog.json
- OpenAPI: https://marketplaceforaiagents.com/api/public/v1/openapi.json
- MCP: https://marketplaceforaiagents.com/mcp
- llms.txt: https://marketplaceforaiagents.com/llms.txt
- Marketplace: https://marketplaceforaiagents.com/marketplace
- Docs: https://marketplaceforaiagents.com/docs
- MCP + x402 guide: https://marketplaceforaiagents.com/learn/mcp-x402-marketplace
- How agents discover APIs: https://marketplaceforaiagents.com/learn/how-ai-agents-discover-apis
- Amazon product API for agents: https://marketplaceforaiagents.com/learn/amazon-asin-api-for-agents
- Google Search for agents: https://marketplaceforaiagents.com/learn/google-search-api-for-agents

Capability first, payment second — find the shopping endpoint, prove it with free calls, then settle unpaid traffic with x402 USDC on Base.

Canonical HTML: https://marketplaceforaiagents.com/learn/google-shopping-api-for-agents