--- type: "firecrawl-provider" description: "Search products across Shopify merchants or within one store, resolve product identifiers and inspect variants through Shopify's UCP catalogs." use_when: "Cross-merchant product discovery and variant evaluation using Shopify UCP.\n\nSearch and inspect products from a single Shopify store using its domain and Storefront Catalog MCP endpoint." categories: "Retail" capabilities: 6 credits_per_call: 5 --- # Shopify on Firecrawl Alexandria Search products across Shopify merchants or within one store, resolve product identifiers and inspect variants through Shopify's UCP catalogs. - Categories: Retail - Category index: [Retail category](https://firecrawl.dev/alexandria/agents/categories/retail) - Provider key: `shopify` - Access: Firecrawl credits - Cost: 5 credits per call ## More - [Human guide](https://firecrawl.dev/app/alexandria/shopify) - [OpenAPI spec](https://firecrawl.dev/alexandria/agents/providers/shopify/openapi.json) ## Capabilities - [Search products](https://firecrawl.dev/alexandria/agents/providers/shopify/catalog/search_catalog): Product records, product metadata and optional messages. Search includes pagination.cursor/has_next_page; repeat the original query with the returned cursor. - [Look up products](https://firecrawl.dev/alexandria/agents/providers/shopify/catalog/lookup_catalog): Product records, product metadata and optional messages. Search includes pagination.cursor/has_next_page; repeat the original query with the returned cursor. - [Product details](https://firecrawl.dev/alexandria/agents/providers/shopify/catalog/get_product): Product records, product metadata and optional messages. Search includes pagination.cursor/has_next_page; repeat the original query with the returned cursor. - [Storefront: Search products](https://firecrawl.dev/alexandria/agents/providers/shopify/storefront/search_catalog): Product records, product metadata and optional messages. Search includes pagination.cursor/has_next_page; repeat the original query with the returned cursor. - [Storefront: Look up products](https://firecrawl.dev/alexandria/agents/providers/shopify/storefront/lookup_catalog): Product records, product metadata and optional messages. Search includes pagination.cursor/has_next_page; repeat the original query with the returned cursor. - [Storefront: Product details](https://firecrawl.dev/alexandria/agents/providers/shopify/storefront/get_product): Product records, product metadata and optional messages. Search includes pagination.cursor/has_next_page; repeat the original query with the returned cursor. ## 1. Choose this provider when Cross-merchant product discovery and variant evaluation using Shopify UCP. Search and inspect products from a single Shopify store using its domain and Storefront Catalog MCP endpoint. ## 2. Minimal request Call `POST https://api.firecrawl.dev/v2/scrape` with `{ alexandria: { provider, capability, options } }`. For a batch, send `{ alexandria: [...] }` with up to 10 calls. ```json { "provider": "shopify", "capability": "catalog/search_catalog", "options": { "query": "trail running shoes", "limit": 10 } } ``` ## 3. Add provider options Use only the options needed for the task: - `query` (string): What are you looking for? For example: `trail running shoes`. Required unless using like for similarity search. Example: `trail running shoes` - `country` (string): Buyer's two-letter country code, such as US, CA or GB, for localized results. Example: `` - `limit` (number): Number of products per page, from 1 to 50. Shopify defaults to 10. Example: `10` - `currency` (string): Three-letter currency code, such as USD, CAD or GBP. Example: `` - `language` (string): Preferred language tag, such as en or en-US. Example: `` - `cursor` (string): For the next page, paste pagination.cursor from the previous response and keep the same search and filters. Example: `` - `region` (string): Buyer's state, province or region, such as CA. Example: `` - `postal_code` (string): Buyer's postal or ZIP code for localized results. Example: `` - `intent` (string): Optional shopping preferences or intended use. Example: `` - `filters` (object): Advanced filters, such as {"available":true,"price":{"max":15000}}. Price amounts use minor currency units: 15000 means USD 150. Example: `{}` - `like` (object[]): Advanced similarity search instead of, or alongside, query. Provide up to two items as {"id":"gid://shopify/..."} or {"image":{"content_type":"image/jpeg","data":""}}. Example: `[]` - `catalog_id` (string): Optional saved Shopify catalog ID to restrict the search. Example: `` - `view` (string): Advanced Shopify output view. Leave empty for the default representation. Example: `` ## 4. Request through your preferred interface ### JavaScript ```javascript const result = await firecrawl.scrape({ alexandria: { provider: "shopify", capability: "catalog/search_catalog", options: { query: "trail running shoes", limit: 10, }, }, }); ``` ### Python ```python result = firecrawl.scrape_alexandria({ "provider": "shopify", "capability": "catalog/search_catalog", "options": { "query": "trail running shoes", "limit": 10 } }) ``` ### cURL ```sh curl https://api.firecrawl.dev/v2/scrape \ -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "alexandria": { "provider": "shopify", "capability": "catalog/search_catalog", "options": { "query": "trail running shoes", "limit": 10 } } }' ``` ### CLI ```sh firecrawl scrape 'shopify/catalog/search_catalog' \ --options '{"query":"trail running shoes","limit":10}' ``` ### MCP Call the FCX MCP retrieve tool with this object: ```json { "provider": "shopify", "capability": "catalog/search_catalog", "options": { "query": "trail running shoes", "limit": 10 } } ``` Ask for only the returned fields needed by the task. ## 5. Full request shape ```json { "provider": "shopify", "capability": "catalog/search_catalog", "options": { "query": "trail running shoes", "limit": 10 } } ``` ## 6. Response data The response includes `success`, `provider`, `capability`, `creditsCost` and `data`. This example shows the provider payload in `data`: ```json { "products": [ { "id": "", "title": "", "description": {}, "price_range": {}, "variants": [], "media": [], "rating": {}, "options": [], "metadata": {} } ] } ``` ## API reference-derived contract The following capability contract is generated from the same normalized Alexandria API reference exposed in the API spec. ### Search products - Capability: `catalog/search_catalog` - Description: Product records, product metadata and optional messages. Search includes pagination.cursor/has_next_page; repeat the original query with the returned cursor. - Instructions: Search products across Shopify merchants by query, such as trail running shoes under $150. Narrow results by country and use limit and cursor to page through them. Results are estimates, not an exhaustive merchant inventory. - Cost: 5 credits per call - Capability file: [Search products](https://firecrawl.dev/alexandria/agents/providers/shopify/catalog/search_catalog) Accepted options: - `query` (string): What are you looking for? For example: `trail running shoes`. Required unless using like for similarity search. Example: `trail running shoes` - `country` (string): Buyer's two-letter country code, such as US, CA or GB, for localized results. Example: `<country>` - `limit` (number): Number of products per page, from 1 to 50. Shopify defaults to 10. Example: `10` - `currency` (string): Three-letter currency code, such as USD, CAD or GBP. Example: `<currency>` - `language` (string): Preferred language tag, such as en or en-US. Example: `<language>` - `cursor` (string): For the next page, paste pagination.cursor from the previous response and keep the same search and filters. Example: `<cursor>` - `region` (string): Buyer's state, province or region, such as CA. Example: `<region>` - `postal_code` (string): Buyer's postal or ZIP code for localized results. Example: `<postal_code>` - `intent` (string): Optional shopping preferences or intended use. Example: `<intent>` - `filters` (object): Advanced filters, such as {"available":true,"price":{"max":15000}}. Price amounts use minor currency units: 15000 means USD 150. Example: `{}` - `like` (object[]): Advanced similarity search instead of, or alongside, query. Provide up to two items as {"id":"gid://shopify/..."} or {"image":{"content_type":"image/jpeg","data":"<base64>"}}. Example: `[]` - `catalog_id` (string): Optional saved Shopify catalog ID to restrict the search. Example: `<catalog_id>` - `view` (string): Advanced Shopify output view. Leave empty for the default representation. Example: `<view>` Response schema example: ```json { "products": [ { "id": "<id>", "title": "<title>", "description": {}, "price_range": {}, "variants": [], "media": [], "rating": {}, "options": [], "metadata": {} } ] } ``` ### Look up products - Capability: `catalog/lookup_catalog` - Description: Product records, product metadata and optional messages. Search includes pagination.cursor/has_next_page; repeat the original query with the returned cursor. - Instructions: Look up 1–50 products using product_ids returned by search, or product URLs. Inspect messages for unmatched identifiers. - Cost: 5 credits per call - Capability file: [Look up products](https://firecrawl.dev/alexandria/agents/providers/shopify/catalog/lookup_catalog) Accepted options: - `product_ids` (string[], required): Paste 1–50 product IDs from search or product URLs. In the web form, separate entries with commas. Example: `[]` - `country` (string): Buyer's two-letter country code, such as US, CA or GB, for localized results. Example: `<country>` - `currency` (string): Three-letter currency code, such as USD, CAD or GBP. Example: `<currency>` - `language` (string): Preferred language tag, such as en or en-US. Example: `<language>` - `region` (string): Buyer's state, province or region, such as CA. Example: `<region>` - `postal_code` (string): Buyer's postal or ZIP code for localized results. Example: `<postal_code>` - `intent` (string): Optional shopping preferences or intended use. Example: `<intent>` - `filters` (object): Advanced filters, such as {"available":true,"price":{"max":15000}}. Price amounts use minor currency units: 15000 means USD 150. Example: `{}` - `view` (string): Advanced Shopify output view. Leave empty for the default representation. Example: `<view>` Response schema example: ```json { "products": [ { "id": "<id>", "title": "<title>", "description": {}, "price_range": {}, "variants": [], "media": [], "rating": {}, "options": [], "metadata": {} } ] } ``` ### Product details - Capability: `catalog/get_product` - Description: Product records, product metadata and optional messages. Search includes pagination.cursor/has_next_page; repeat the original query with the returned cursor. - Instructions: Get details, variants and availability for a product_id returned by search or lookup. Optional selected options refine the variant. Does not create a cart or place an order. - Cost: 5 credits per call - Capability file: [Product details](https://firecrawl.dev/alexandria/agents/providers/shopify/catalog/get_product) Accepted options: - `product_id` (string, required): Paste one product ID returned by search or lookup in the same catalog. Example: `<product_id>` - `country` (string): Buyer's two-letter country code, such as US, CA or GB, for localized results. Example: `<country>` - `currency` (string): Three-letter currency code, such as USD, CAD or GBP. Example: `<currency>` - `language` (string): Preferred language tag, such as en or en-US. Example: `<language>` - `region` (string): Buyer's state, province or region, such as CA. Example: `<region>` - `postal_code` (string): Buyer's postal or ZIP code for localized results. Example: `<postal_code>` - `intent` (string): Optional shopping preferences or intended use. Example: `<intent>` - `filters` (object): Advanced filters, such as {"available":true,"price":{"max":15000}}. Price amounts use minor currency units: 15000 means USD 150. Example: `{}` - `selected` (object[]): Optional variant selections, such as [{"name":"Color","label":"Black"}]. Example: `[]` - `preferences` (string[]): Optional preferences to help select a variant. Example: `[]` - `view` (string): Advanced Shopify output view. Leave empty for the default representation. Example: `<view>` Response schema example: ```json { "product": { "id": "<id>", "title": "<title>", "description": {}, "price_range": {}, "variants": [], "media": [], "rating": {}, "options": [], "metadata": {}, "selected": [] } } ``` ### Storefront: Search products - Capability: `storefront/search_catalog` - Description: Product records, product metadata and optional messages. Search includes pagination.cursor/has_next_page; repeat the original query with the returned cursor. - Instructions: Search products in a Shopify store by store_domain and query, or leave query empty to browse. Use limit and cursor for pagination. The store must expose Shopify's Storefront Catalog endpoint. - Cost: 5 credits per call - Capability file: [Storefront: Search products](https://firecrawl.dev/alexandria/agents/providers/shopify/storefront/search_catalog) Accepted options: - `store_domain` (string, required): Store domain, such as `www.lemsshoes.com`. Enter the canonical hostname without https://, a path or port. Example: `www.lemsshoes.com` - `query` (string): What are you looking for? For example: `trail shoes`. Leave empty to browse the store. Example: `trail shoes` - `country` (string): Buyer's two-letter country code, such as US, CA or GB, for localized results. Example: `<country>` - `limit` (number): Number of products per page, from 1 to 250. Shopify defaults to 10. Example: `10` - `currency` (string): Three-letter currency code, such as USD, CAD or GBP. Example: `<currency>` - `language` (string): Preferred language tag, such as en or en-US. Example: `<language>` - `cursor` (string): For the next page, paste pagination.cursor from the previous response and keep the same search and filters. Example: `<cursor>` - `region` (string): Buyer's state, province or region, such as CA. Example: `<region>` - `postal_code` (string): Buyer's postal or ZIP code for localized results. Example: `<postal_code>` - `intent` (string): Optional shopping preferences or intended use. Example: `<intent>` - `filters` (object): Advanced filters, such as {"available":true,"price":{"max":15000}}. Price amounts use minor currency units: 15000 means USD 150. Example: `{}` Response schema example: ```json { "products": [ { "id": "<id>", "title": "<title>", "description": {}, "price_range": {}, "variants": [], "media": [], "options": [], "url": "<url>", "handle": "<handle>", "list_price_range": {}, "categories": [], "tags": [], "gift_card": false, "collections": [] } ] } ``` ### Storefront: Look up products - Capability: `storefront/lookup_catalog` - Description: Product records, product metadata and optional messages. Search includes pagination.cursor/has_next_page; repeat the original query with the returned cursor. - Instructions: Look up 1–10 product_ids within store_domain. Use IDs returned by that store's search, not Global Catalog IDs. Inspect messages for unmatched identifiers. - Cost: 5 credits per call - Capability file: [Storefront: Look up products](https://firecrawl.dev/alexandria/agents/providers/shopify/storefront/lookup_catalog) Accepted options: - `store_domain` (string, required): Store domain, such as `www.lemsshoes.com`. Enter the canonical hostname without https://, a path or port. Example: `www.lemsshoes.com` - `product_ids` (string[], required): Paste 1–10 product IDs from search in this store. In the web form, separate entries with commas. Example: `[]` - `country` (string): Buyer's two-letter country code, such as US, CA or GB, for localized results. Example: `<country>` - `currency` (string): Three-letter currency code, such as USD, CAD or GBP. Example: `<currency>` - `language` (string): Preferred language tag, such as en or en-US. Example: `<language>` - `region` (string): Buyer's state, province or region, such as CA. Example: `<region>` - `postal_code` (string): Buyer's postal or ZIP code for localized results. Example: `<postal_code>` - `intent` (string): Optional shopping preferences or intended use. Example: `<intent>` - `filters` (object): Advanced filters, such as {"available":true,"price":{"max":15000}}. Price amounts use minor currency units: 15000 means USD 150. Example: `{}` Response schema example: ```json { "products": [ { "id": "<id>", "title": "<title>", "description": {}, "price_range": {}, "variants": [], "media": [], "options": [], "url": "<url>", "handle": "<handle>", "list_price_range": {}, "categories": [], "tags": [], "gift_card": false, "collections": [] } ] } ``` ### Storefront: Product details - Capability: `storefront/get_product` - Description: Product records, product metadata and optional messages. Search includes pagination.cursor/has_next_page; repeat the original query with the returned cursor. - Instructions: Get details and availability for a product_id from the selected store's search or lookup. Keep the same store_domain. Optional selected options refine the variant without executing checkout. - Cost: 5 credits per call - Capability file: [Storefront: Product details](https://firecrawl.dev/alexandria/agents/providers/shopify/storefront/get_product) Accepted options: - `store_domain` (string, required): Store domain, such as `www.lemsshoes.com`. Enter the canonical hostname without https://, a path or port. Example: `www.lemsshoes.com` - `product_id` (string, required): Paste one product ID returned by search or lookup in the same catalog. Example: `<product_id>` - `country` (string): Buyer's two-letter country code, such as US, CA or GB, for localized results. Example: `<country>` - `currency` (string): Three-letter currency code, such as USD, CAD or GBP. Example: `<currency>` - `language` (string): Preferred language tag, such as en or en-US. Example: `<language>` - `region` (string): Buyer's state, province or region, such as CA. Example: `<region>` - `postal_code` (string): Buyer's postal or ZIP code for localized results. Example: `<postal_code>` - `intent` (string): Optional shopping preferences or intended use. Example: `<intent>` - `filters` (object): Advanced filters, such as {"available":true,"price":{"max":15000}}. Price amounts use minor currency units: 15000 means USD 150. Example: `{}` - `selected` (object[]): Optional variant selections, such as [{"name":"Color","label":"Black"}]. Example: `[]` - `preferences` (string[]): Optional preferences to help select a variant. Example: `[]` Response schema example: ```json { "product": { "id": "<id>", "title": "<title>", "description": {}, "price_range": {}, "variants": [], "media": [], "options": [], "url": "<url>", "handle": "<handle>", "list_price_range": {}, "categories": [], "tags": [], "gift_card": false, "collections": [], "selected": [] } } ```