Shopify 店铺数据抓取 API

Response notes

- Returns the requested storefront URL plus the resolved source URL used for JSON requests. - Includes `myshopify_domain`, store name, currency, country, and published product/collection counts when `/meta.json` exposes them. - Blocked pages, malformed JSON, missing Shopify roots, and unavailable fallback domains return upstream errors. - For some storefronts, `transport_mode` is `ssr_embedded`; it is omitted entirely for other stores. Responses for these stores may have fewer populated fields (for example `myshopify_domain` and the store-metadata fields are typically unavailable). `transport_mode` allowed values: `ssr_embedded` (only ever present, never any other value; omitted for the classic transport).

Response notes

- Valid empty result pages return `200` with an empty `products` array. - Product prices are normalized to decimal currency units. - Blocked pages, malformed JSON, and missing `products` roots return upstream errors. - For some storefronts, the response includes `transport_mode: "ssr_embedded"`, `total_items`, and `total_pages` (the storefront's own result-count/page-count metadata), and each product may include additive fields only available from this source: `colour`, `canonical_colour`, `discount_percentage`, `rating`, `rating_count`, `collection_tags`, `labels`, and per-variant `inventory_quantity`. `limit` is still honored as an upper bound on returned items, but the underlying page size is fixed by the storefront (commonly 60) and cannot be requested larger than that. `transport_mode`, `total_items`, and `total_pages` are omitted entirely for other stores. - When `transport_mode` is `ssr_embedded`, the response may also include `facets` and `facets_stats`, mirroring the storefront's own filter sidebar for that listing: `facets` maps a facet field name exactly as the storefront names it (for example `fit`, `activities`, `canonicalColour`, `sizeInStock`) to its value-to-count buckets, and `facets_stats` gives `min`/`max`/`avg` for numeric-range fields such as `price` and `discountPercentage`. Both are omitted when the storefront's payload did not include facet data, and always omitted for other stores. - **`sortBy` and facet filters apply to `ssr_embedded` stores only.** Rather than silently accepting and ignoring `sortBy` or a facet filter against other stores (which would look like it worked but wouldn't), this endpoint rejects the request with a `400` invalid-param error whenever `sortBy` or any facet-filter query param is supplied and the resolved store is not `transport_mode: "ssr_embedded"`. - When a sort and/or filters were applied to an `ssr_embedded` store, the response echoes back what was actually honored: `sort` (one of the enum values below) and `filters` (a map of facet field name to the array of values that were requested for it, after comma-splitting). Both are omitted when no sort/filter was supplied. - `hitsPerPage` (the storefront's own listing page size, commonly 60) is unaffected by sort/filters; `limit` continues to apply as an upper bound on the returned page. - **Storefront Filtering** (`sort_by`/`min_price`/`max_price`/`product_type`/`in_stock_only`/`option_*`) is Shopify's own native collection-page filtering/sorting feature, distinct from the `sortBy`/dynamic-facet-filter pair above. It works for all stores. When any of these params is supplied, the response has `transport_mode: "storefront_filtered"` and echoes back the effective `sort_by`, `min_price`, `max_price`, `product_type`, `in_stock_only`, and `variant_options` that were applied. `facets`/`facets_stats` are populated from the storefront's own filter sidebar when present: `facets` maps a lowercased variant option name (e.g. `size`, `color`) or `product_type` to its value-to-count buckets, and `facets_stats.price` gives the Price slider's own `min`/`max` bounds. `total_pages` is populated only when the collection page itself renders numbered pagination links; a single-page result leaves it unset. Not every Shopify store has this feature enabled — a store without it returns the unfiltered/unsorted collection page, which this endpoint cannot distinguish from "the filter matched everything" without upstream signal. `sortBy` allowed values: `sortLTH`, `sortHTL`, `newest`. `sort_by` allowed values: `manual`, `best-selling`, `title-ascending`, `title-descending`, `price-ascending`, `price-descending`, `created-ascending`, `created-descending`. `transport_mode` allowed values: `ssr_embedded`, `storefront_filtered` (omitted entirely for the classic transport).

Response notes

- Product prices are returned in decimal currency units rather than cent values. - Missing product handles return `404` when Shopify returns not found. - Blocked pages, malformed JSON, and missing product fields return upstream errors. - For some storefronts, the response includes `transport_mode: "ssr_embedded"`, and the product may include additive fields only available from this source: `colour`, `canonical_colour`, `discount_percentage`, `rating`, `rating_count`, `collection_tags`, `labels`, and per-variant `inventory_quantity`. `transport_mode` is omitted entirely for other stores. A product for which no detail data is available returns an upstream error. `transport_mode` allowed values: `ssr_embedded` (only ever present, never any other value; omitted for the classic transport).

Response notes

- Missing product handles return `404` when Shopify returns not found while resolving the seed product. - Valid empty recommendation arrays return `200` with an empty `products` array. - Blocked pages, malformed JSON, and missing Shopify roots return upstream errors. - For some storefronts, the response includes `transport_mode: "ssr_embedded"`, and each product may include the same additive fields documented for `/shopify/products`: `colour`, `canonical_colour`, `discount_percentage`, `rating`, `rating_count`, `collection_tags`, `labels`, and per-variant `inventory_quantity`. `transport_mode` is omitted entirely for other stores. `transport_mode` allowed values: `ssr_embedded` (only ever present, never any other value; omitted for the classic transport).

Response notes

- Valid empty result pages return `200` with an empty `collections` array. - Blocked pages, malformed JSON, and missing `collections` roots return upstream errors. - For some storefronts, the response includes `transport_mode: "ssr_embedded"`, and `title` is a best-effort derivation from the handle (hyphens become spaces, each word title-cased) — **not** the storefront's real display name. `products_count` and other fields not available for these storefronts are omitted, never fabricated. `transport_mode` is omitted entirely for other stores. - In this fallback mode, `handle` is derived from the last path segment of the collection URL and is not guaranteed unique: some storefronts nest gender/audience-scoped sub-collections under the same final segment (for example `/collections/all-products/womens` and `/collections/legacy/womens` both derive `handle: "womens"`). Use the item's own `url` to identify a specific nested collection rather than assuming `handle` alone round-trips through `GET /shopify/collections/{handle}/products`. `transport_mode` allowed values: `ssr_embedded` (only ever present, never any other value; omitted for the classic transport).

Response notes

- Valid empty result pages return `200` with an empty `products` array. - Missing collections return `404` when Shopify returns not found. - Blocked pages, malformed JSON, and missing `products` roots return upstream errors. - For some storefronts, the response includes `transport_mode: "ssr_embedded"`, `total_items`, and `total_pages` (the storefront's own result-count/page-count metadata), and each product may include additive fields only available from this source: `colour`, `canonical_colour`, `discount_percentage`, `rating`, `rating_count`, `collection_tags`, `labels`, and per-variant `inventory_quantity`. `limit` is still honored as an upper bound on returned items, but the underlying page size is fixed by the storefront (commonly 60) and cannot be requested larger than that. `transport_mode`, `total_items`, and `total_pages` are omitted entirely for other stores. - When `transport_mode` is `ssr_embedded`, the response may also include `facets` and `facets_stats`, mirroring the collection page's own filter sidebar: `facets` maps a facet field name exactly as the storefront names it (for example `fit`, `activities`, `canonicalColour`, `sizeInStock`) to its value-to-count buckets, and `facets_stats` gives `min`/`max`/`avg` for numeric-range fields such as `price` and `discountPercentage`. Both are omitted when the storefront's payload did not include facet data, and always omitted for other stores. - **`sortBy` and facet filters apply to `ssr_embedded` stores only.** Rather than silently accepting and ignoring `sortBy` or a facet filter against other stores (which would look like it worked but wouldn't), this endpoint rejects the request with a `400` invalid-param error whenever `sortBy` or any facet-filter query param is supplied and the resolved store is not `transport_mode: "ssr_embedded"`. - When a sort and/or filters were applied to an `ssr_embedded` store, the response echoes back what was actually honored: `sort` (one of the enum values below) and `filters` (a map of facet field name to the array of values that were requested for it, after comma-splitting). Both are omitted when no sort/filter was supplied. - `hitsPerPage` (the storefront's own listing page size, commonly 60) is unaffected by sort/filters; `limit` continues to apply as an upper bound on the returned page. - **Storefront Filtering** (`sort_by`/`min_price`/`max_price`/`product_type`/`in_stock_only`/`option_*`) is Shopify's own native collection-page filtering/sorting feature, distinct from the `sortBy`/dynamic-facet-filter pair above. It works for all stores. When any of these params is supplied, the response has `transport_mode: "storefront_filtered"` and echoes back the effective `sort_by`, `min_price`, `max_price`, `product_type`, `in_stock_only`, and `variant_options` that were applied. `facets`/`facets_stats` are populated from the collection page's own filter sidebar when present: `facets` maps a lowercased variant option name (e.g. `size`, `color`) or `product_type` to its value-to-count buckets, and `facets_stats.price` gives the Price slider's own `min`/`max` bounds. `total_pages` is populated only when the collection page itself renders numbered pagination links; a single-page result leaves it unset. Not every Shopify store has this feature enabled — a store without it returns the unfiltered/unsorted collection page, which this endpoint cannot distinguish from "the filter matched everything" without upstream signal. `sortBy` allowed values: `sortLTH`, `sortHTL`, `newest`. `sort_by` allowed values: `manual`, `best-selling`, `title-ascending`, `title-descending`, `price-ascending`, `price-descending`, `created-ascending`, `created-descending`. `transport_mode` allowed values: `ssr_embedded`, `storefront_filtered` (omitted entirely for the classic transport).

Response notes

- Products and collections use the same shapes as the Shopify product and collection endpoints. - Query suggestions include text and a storefront search URL when Shopify provides one. - Valid empty suggestion arrays return `200` with empty arrays. - Blocked pages, malformed JSON, and missing Shopify roots return upstream errors.

Response notes

- Page content is cleaned text from Shopify `body_html`; raw HTML is not returned. - Valid empty page arrays return `200` with an empty `pages` array. - Blocked pages, malformed JSON, and missing Shopify roots return upstream errors. - For some storefronts, the response includes `transport_mode: "ssr_embedded"`, and each item only carries `handle`, `url`, and `updated_at` — no `title`, `id`, or `content`. Call `GET /shopify/pages/{handle}` per handle to get full content. `transport_mode` is omitted entirely for other stores. `transport_mode` allowed values: `ssr_embedded` (only ever present, never any other value; omitted for the classic transport).

Response notes

- Page content is cleaned text from Shopify `body_html`; raw HTML is not returned. - Missing page handles return `404` when Shopify returns not found. - Blocked pages, malformed JSON, and missing Shopify roots return upstream errors. - For some storefronts, the response includes `transport_mode: "ssr_embedded"`; `content` is plain text rendered from the page's rich-text blocks (marks/formatting are dropped, non-rich-text blocks such as banners are skipped), and `id` is omitted because it is not a Shopify numeric id. `transport_mode` is omitted entirely for other stores. `transport_mode` allowed values: `ssr_embedded` (only ever present, never any other value; omitted for the classic transport).

Response notes

- Sitemap `type` is inferred from the child sitemap URL. - Inferred sitemap types are `products`, `collections`, `pages`, `blogs`, `agentic_discovery`, and `other`. - Blocked pages, malformed XML, and missing sitemap entries return upstream errors.

Response notes

- The service fetches matching child sitemaps from `/sitemap.xml` until `limit` URL entries is reached. - URL entries include `loc`, inferred `type`, `handle`, `lastmod`, `changefreq`, and optional `images`. - Blocked pages, malformed XML, and missing sitemap entries return upstream errors.