Google Shopping Product API

The Google Shopping Product API is the companion endpoint to /plugin/google/shopping. It fetches the full product page for a single Google Shopping product — every seller offer, variants, specs, reviews, videos, and related discussions — as structured JSON.

The recommended flow is three steps: call /plugin/google/shopping to find a product, capture its catalog_id, hit this endpoint to get the product page with its first sellers, then replay the next_page_token against /plugin/google/shopping/product/stores to walk the rest of the seller list. Add gpcid when you need every offer from the specific cluster opened by a Google Shopping result card instead of the catalog-wide seller list.

Key Features

• Durable Catalog Input: Pass catalog_id to look up a product by its long-lived Google catalog identifier. Catalog IDs are stable per region, so you can save them in your own storage and replay them later.
• Offer Cluster Targeting: Add the gpcid from a Google Shopping product link to return every seller shown on that result card's cluster page without mixing in offers from other clusters.
• Rich Product Data: Title, gallery, brand, rating, ratings histogram, thumbnails, variants, specs, videos, customer review images, top insights, related discussions — all parsed into structured fields.
• Large Seller Lists: The default catalog page returns the headline ~5 sellers and a continuation token (next_page_token). Replay it against /plugin/google/shopping/product/stores to walk up to ~1,000 sellers. Pass load_all_stores=true to have the gateway walk the first ~100 sellers for you in a single request.
• Variant Filtering: In token mode, pass pvf to narrow stores[] to one variant's offers (a colour, a size, a storage capacity) instead of the union of every variant's offers. See Variant filter.
• Per-seller Detail: Price, shipping, tax, total, payment methods, delivery / returns details, merchant ID, thumbnail, badge text, sale & strikethrough prices, and carrier-style monthly installment plans (installment_months, installment_down_now, total) when applicable.
• Three Response Modes: catalog_oapv (catalog mode, recommended), oapv (token mode, rich short-lived payload), and html (legacy product-id-only fallback). The chosen mode is echoed in product_results.source.
• Worldwide Coverage: Locale via gl + hl + location / uule; carrier financing and EU comma-decimal formatting handled automatically.
• Device Emulation: Desktop, mobile, or tablet layout with the device parameter.
• No Blocks or CAPTCHAs: All anti-bot measures are handled automatically by Scrape.do.

Endpoint

GET https://api.scrape.do/plugin/google/shopping/product

Request Parameters

Required

Identity (choose one)

Provide one of the identifiers below. When you supply more than one, the priority is catalog_id > immersive_product_page_token > product_id.

Offer cluster

Google can divide one catalog into multiple offer clusters. A link containing only prds=catalogid:11098835974841238015 opens the catalog-wide product page. A link containing prds=catalogid:11098835974841238015,gpcid:3719569561376036875,… opens one cluster, which can have a different title and seller list.

Pass catalog_id alone for catalog-wide price comparison. Add gpcid when you need every seller shown on the specific cluster page opened by a result card. A cluster response usually contains 1–5 offers, does not include next_page_token, and is not expanded by load_all_stores=true, so sellers from other clusters are never mixed into the result.

Device

Routing

Sort

Variant filter

Without pvf, stores[] is the union of every variant's offers — the same list Google shows before you pick a swatch. A product sold in three colours and three capacities returns offers mixing all nine combinations, so a price comparison across them is not like-for-like.

Filtering takes two calls:

1. Call the endpoint with no pvf and read product_results.variants[]. Every option you can switch to carries the pvf value that selects it; the option already selected and the "Any" option (such as Any Color) have none.
2. Call the endpoint again with that value as pvf. stores[] now contains only offers for that variant, and variants[].options[].selected flags the option you applied.

selected appears only on the option currently applied on that variant axis — it previously came back on every option, so code that filtered on it used to match the whole list.

product_results.applied_pvf echoes the filter Google actually applied. It is absent when you sent no pvf — so if you did send one and applied_pvf is missing, the filter did not take effect and stores[] is unfiltered.

pvf combines with more_stores, which widens the seller window from ~5 to ~10. A filtered list does not paginate beyond that — no next_page_token is returned on a pvf-filtered response, because a continuation cursor cannot carry the filter and would page you back into unfiltered results. It does not combine with sort_by, product_id, or catalog_id: those select modes that cannot filter, so they return 400 rather than silently ignoring the filter.

Seller list expansion

Localization

See Localization for the full list of supported hl, gl, and google_domain values.

Example Usage

By catalog_id (recommended — durable input)

# 1. Look up the product and grab its catalog_id
CID=$(curl -s "https://api.scrape.do/plugin/google/shopping?q=PodTrak+P8+ZP8&hl=en&gl=us&token=YOUR_TOKEN" \
  | jq -r '.shopping_results[0].catalog_id')

# 2. Fetch the product page + first sellers + continuation token
curl "https://api.scrape.do/plugin/google/shopping/product?catalog_id=$CID&q=PodTrak+P8+ZP8&hl=en&gl=us&token=YOUR_TOKEN"

q is optional. If you already have a Google Shopping product link, you can call the endpoint with its catalogid: value alone:

curl "https://api.scrape.do/plugin/google/shopping/product?catalog_id=11098835974841238015&gl=us&token=YOUR_TOKEN"

By offer cluster

Use the catalogid: and gpcid: values from the same product link to return all offers on that cluster page:

curl "https://api.scrape.do/plugin/google/shopping/product?catalog_id=11098835974841238015&gpcid=3719569561376036875&gl=us&token=YOUR_TOKEN"

Catalog mode in another market

# Same product, German market — re-search per region to get the region-scoped catalog_id
CID=$(curl -s "https://api.scrape.do/plugin/google/shopping?q=iPhone+17+Pro&hl=de&gl=de&token=YOUR_TOKEN" \
  | jq -r '.shopping_results[0].catalog_id')

curl "https://api.scrape.do/plugin/google/shopping/product?catalog_id=$CID&q=iPhone+17+Pro&hl=de&gl=de&token=YOUR_TOKEN"

Load the first ~100 sellers in one call

curl "https://api.scrape.do/plugin/google/shopping/product?catalog_id=$CID&q=PodTrak+P8+ZP8&load_all_stores=true&token=YOUR_TOKEN"

By immersive_product_page_token (rich short-lived response)

# 1. Mint a token from the search endpoint
TOKEN=$(curl -s "https://api.scrape.do/plugin/google/shopping?q=Sony+WH-1000XM5&token=YOUR_TOKEN" \
  | jq -r '.shopping_results[0].immersive_product_page_token')

# 2. Replay it against the product endpoint (variants/specs/reviews/videos returned)
curl "https://api.scrape.do/plugin/google/shopping/product?immersive_product_page_token=$TOKEN&token=YOUR_TOKEN"

Filter by variant (pvf, token mode)

# 1. Mint a token from the search endpoint
TOKEN=$(curl -s "https://api.scrape.do/plugin/google/shopping?q=Sony+WH-1000XM5&token=YOUR_TOKEN" \
  | jq -r '.shopping_results[0].immersive_product_page_token')

# 2. Fetch the product with no filter and read the options.
#    stores[] mixes every variant; each option carries the pvf that selects it.
curl "https://api.scrape.do/plugin/google/shopping/product?immersive_product_page_token=$TOKEN&token=YOUR_TOKEN"

# 3. Call again with the pvf of the option you want.
curl "https://api.scrape.do/plugin/google/shopping/product?immersive_product_page_token=$TOKEN&pvf=Eg8iBWNvbG9yKgZzaWx2ZXI&token=YOUR_TOKEN"
# → every row in stores[] is an offer for that variant, and applied_pvf echoes the filter

By product_id (HTML fallback)

curl "https://api.scrape.do/plugin/google/shopping/product?product_id=7000474567848623813&token=YOUR_TOKEN"

Response

Top-Level Structure

{
  "search_parameters": { ... },
  "product_results":   { ... }
}

search_parameters

Echo of the request parameters sent by the client.

{
  "engine": "google_shopping_product",
  "product_id": "7000474567848623813",
  "page_token": "eyJlaSI6ImFhX1Nh...",
  "google_domain": "google.com",
  "hl": "en",
  "gl": "us",
  "device": "desktop",
  "more_stores": false,
  "next_page_token": ""
}

Optional fields appear only when sent: gpcid, location, uule, and sort_by. Catalog mode always echoes catalog_id, q (empty when you omit it), and load_all_stores.

product_results (rich path)

Returned when you pass immersive_product_page_token and do not pass sort_by. source is "oapv".

{
  "title": "Sony WH-1000XM5 Wireless Noise Canceling Headphones",
  "product_id": "7000474567848623813",
  "brand": "Sony",
  "rating": 4.6,
  "reviews": 4800,
  "reviews_label": "4,800 reviews",
  "ratings": [
    { "stars": 5, "count": 3400 },
    { "stars": 4, "count": 900 }
  ],
  "thumbnails": [ "https://encrypted-tbn0.gstatic.com/...", "..." ],
  "reviews_images": [ "https://encrypted-tbn0.gstatic.com/...", "..." ],
  "stores": [ { /* see stores[] table below */ } ],
  "next_page_token": "eyJzb3JpIjo1LCJtbm8iOjEwfQ",
  "variants": [ { "type": "Color", "options": [ { "text": "Any Color" }, { "text": "Black", "selected": true }, { "text": "Silver", "pvf": "Eg8iBWNvbG9yKgZzaWx2ZXI", "shoprs": "Eg8iBWNvbG9yKgZzaWx2ZXI" } ] } ],
  "specs": [ { "section": "General", "items": [ { "label": "Wireless", "value": "Yes" } ] } ],
  "videos": [ { "title": "Sony WH-1000XM5 Review", "source": "youtube.com", "thumbnail": "...", "link": "..." } ],
  "user_reviews": [ { "rating": 5, "title": "Best headphones", "body": "...", "author": "John D." } ],
  "top_insights": [ { "section": "Sound quality", "items": [ "Crystal-clear audio", "Strong bass" ] } ],
  "about_the_product": { "description": "..." },
  "more_options": [ { "title": "Sony WH-1000XM4", "link": "...", "thumbnail": "..." } ],
  "discussions_and_forums": [ { "title": "...", "source": "reddit.com", "link": "...", "snippet": "..." } ],
  "extension_ids": { "catalog_id": "...", "gpcid": "..." },
  "source": "oapv"
}

product_results (HTML fallback)

Returned when you pass only product_id, or when you pass sort_by alongside the token. source is "html". Lean shape — no variants, specs, videos, or reviews — but the seller list works.

{
  "title": "Sony WH-1000XM5 Wireless Noise Canceling Headphones",
  "product_id": "7000474567848623813",
  "stores": [ { /* see stores[] table below */ } ],
  "source": "html"
}

stores[] Fields

Each entry in product_results.stores[] describes a single merchant offer for the product.

In catalog mode, the first 3–5 stores[] entries come from the product page and include the merchant name, link, title, price, shipping, rating, and tag, plus sale and installment fields when shown. Sellers added through load_all_stores=true or /plugin/google/shopping/product/stores come from Google's continuation feed and can also include currency, total, details_and_offers, logo, and thumbnail.

Three Response Modes

The plugin picks the response mode automatically based on what you sent:

Inspect product_results.source to know which mode served the response. Catalog mode is the recommended default for any workflow that persists product identifiers.

The pvf variant filter is supported in token mode only — sending it with catalog_id, product_id, or sort_by returns HTTP 400.

Paginating every seller

Catalog mode without gpcid returns up to ~5 sellers inline plus a next_page_token when more remain. For catalogs that group multiple sizes, finishes, colors, or other variants, the first response and every continuation page stay on the variant Google selected for that catalog_id. If Google cannot provide a variant-pinned view, the endpoint returns the first seller page without a next_page_token rather than continuing with offers from other variants. Use catalog pagination in one of two ways:

Option 1 — Manual pagination via /plugin/google/shopping/product/stores

The dedicated continuation endpoint accepts the signed token and returns the next batch of sellers (up to ~10 per call). It's the most cost-efficient path because each call is a single hop when the embedded session is still fresh.

GET https://api.scrape.do/plugin/google/shopping/product/stores

# After the catalog call:
NEXT=$(echo "$RESP" | jq -r '.product_results.next_page_token // empty')

while [ -n "$NEXT" ]; do
  RESP=$(curl -s "https://api.scrape.do/plugin/google/shopping/product/stores?catalog_id=$CID&next_page_token=$NEXT&token=YOUR_TOKEN")
  echo "$RESP" | jq '.product_results.stores | length'
  NEXT=$(echo "$RESP" | jq -r '.product_results.next_page_token // empty')
done

Response shape is lean — only product_id, stores[], and (when more sellers remain) next_page_token. Title, gallery, variants, etc. are not re-emitted; you already have them from the catalog call. source is "catalog_oapv_more".

The token is signed and bound to the supplied catalog_id. Sending a different catalog_id returns HTTP 400 ("catalog_id mismatch").

Each continuation call returns up to ~10 sellers, and pagination can continue to roughly 1,000 sellers. A short final page has no next_page_token. If a full page reaches the safety limit instead, it also omits next_page_token but includes Scrape.do-Auto-Page-Truncated: true, so you can distinguish truncation from the natural end of the list.

Google can repeat a seller on later pages in long result sets. When combining pages, de-duplicate offers by merchant_id.

Option 2 — One-shot load_all_stores=true

For workflows that want a larger seller batch in a single response, pass load_all_stores=true on the catalog call. The gateway walks the continuation cursor for you and returns the merged seller list. The walk is billed per upstream hop and capped at about 10 pages (~100 sellers) by default. If the cap is reached or a later page fails, the response keeps the sellers collected so far and includes a next_page_token for manual continuation plus the Scrape.do-Auto-Page-Truncated: true response header. If the walk fails before collecting any sellers, the endpoint returns HTTP 502 and the request is not charged.

curl "https://api.scrape.do/plugin/google/shopping/product?catalog_id=$CID&q=iPhone+17+Pro&load_all_stores=true&token=YOUR_TOKEN"

Legacy more_stores on the token path

The legacy token flow (immersive_product_page_token) uses more_stores=true to inline the expanded seller list. New integrations should prefer the catalog path; more_stores stays available for existing callers.

Handling Session Expiry

immersive_product_page_token values are tied to an upstream Google session that ages out after several hours. When that happens, the plugin returns HTTP 410 Gone:

{
  "error": "session expired",
  "message": "The immersive_product_page_token is older than 6h0m0s and is past Google's product-viewer session lifetime. Fetch /plugin/google/shopping again to mint a fresh token, then retry."
}

(The exact lifetime message may vary; the recovery is always the same.)

See Transient Errors for the full rotate-on-expiry pattern.

Error Handling

All endpoints return errors in a consistent JSON format:

{
  "error": "error_code",
  "message": "Human readable error message"
}

Common Error Codes