Shopify API endpoint
Returns recommended products from Shopify's product recommendations.
/shopify/products/{handle}/recommendationsReturns recommended products from Shopify.
handle: required. Product handle.url: required. Full Shopify storefront URL, using http or https. Localhost, private network, link-local, and credentialed URLs are rejected.limit: optional. Defaults to 10, maximum 20.intent: optional. Allowed values: related, complementary. Defaults to related.404 when Shopify returns not found while resolving the seed product.200 with an empty products array.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).
| Field | Filled in, of 10 checked | Values in the sample |
|---|---|---|
| id | 10 | |
| handle | 10 | |
| title | 10 | “Men's Tree Runner NZ - Mushroom (Mushroom Sole)” and 9 other values |
| url | 10 | allbirds.com |
| description | 9 | median 253 characters |
| vendor | 10 | Allbirds (9), re:do (1) |
| product_type | 10 | Shoes (8), return,package_protection (1), Apparel (1) |
| published_at | 10 | 2026-06-11 to 2026-09-25 |
| created_at | 10 | 2025-06-20 to 2026-06-05 |
| price | 10 | 14 to 100, median 100 |
| available | 10 | true in 10 of 10 |
| options | 10 | median 1 entry |
| variants | 10 | median 13 entries |
| images | 10 | median 5 entries |
| featured_image | 10 | cdn.shopify.com |
| compare_at_price | 1 | 298 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| handle (path) | string | Yes | Product handle | mens-wool-runners | |
| url | string | Yes | Shopify storefront URL | https://www.allbirds.com | |
| limit | integer | No | 10 and supports up to 20 | Maximum products, defaults to 10 and supports up to 20 | 10 |
| intent | string | No | Recommendation intent. Allowed values: related, complementary Allowed values: related, complementary. | related | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/shopify/products/mens-wool-runners/recommendations?url=https%3A%2F%2Fwww.allbirds.com&limit=10&intent=related" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"store_url": "https://www.allbirds.com",
"source_url": "https://www.allbirds.com",
"handle": "mens-wool-runners",
"product_id": "6616124981328",
"intent": "related",
"limit": 10,
"products": [
{
"handle": "mens-tree-runners",
"title": "Men's Tree Runners"
}
]
}
}Request schema
No body schema
Response schema
#/definitions/shopify.productRecommendationsResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | shopify.ProductRecommendationsResponse | No | ||||
| data.handle | string | No | mens-wool-runners | Handle of the product the recommendations are based on. | ||
| data.intent | string | No | related | Recommendation type returned: `related` or `complementary`. | ||
| data.limit | integer | No | 10 | Maximum number of recommended products returned. | ||
| data.product_id | string | No | 6616124981328 | Shopify id of the product the recommendations are based on. | ||
| data.products | array | No | Recommended products, one item per product. | |||
| data.products[].available | boolean | No | Whether at least one variant is available to buy. | |||
| data.products[].canonical_colour | string | No | black | Main colour name the storefront groups the product under, for example `black`. | ||
| data.products[].collection_tags | array | No | Collections the product is listed in, as the storefront labels them. | |||
| data.products[].colour | string | No | black | The fields below are only populated when the product was resolved via the embedded-SSR-JSON fallback transport (see ssr_fallback.go) and the source page exposed this data; they are additive and never populated for classic-store responses. | ||
| data.products[].compare_at_price | number | No | 120 | Original price before discount, in the store's currency. The highest compare-at price across variants. | ||
| data.products[].condition | string | No | Excellent | Condition is only populated for resale-marketplace search results (Fashionphile's AlgoliaSearch, Rebag's StorefrontSearch -- see search.go) whose catalog data exposes a condition grade. Never populated for any other brand or endpoint in this family. | ||
| data.products[].created_at | string | No | Time the record was created, as Shopify returns it. | |||
| data.products[].description | string | No | Product description as plain text. | |||
| data.products[].discount_percentage | number | No | 20 | Discount currently applied to the product, as a percentage. | ||
| data.products[].featured_image | string | No | URL of the product's main image. | |||
| data.products[].handle | string | No | mens-wool-runners | URL slug of the product, for example `mens-wool-runners`. | ||
| data.products[].id | string | No | 6616124981328 | Shopify product id. | ||
| data.products[].images | array | No | Images of the product, in the storefront's order. | |||
| data.products[].images[].alt | string | No | Product image | Alternative text of the image. | ||
| data.products[].images[].created_at | string | No | Time the record was created, as Shopify returns it. | |||
| data.products[].images[].height | integer | No | 1600 | Image height in pixels. | ||
| data.products[].images[].id | string | No | 36411373027408 | Shopify image id. | ||
| data.products[].images[].position | integer | No | 1 | Position of the image in the product's image list, starting at 1. | ||
| data.products[].images[].updated_at | string | No | Time the record was last updated, as Shopify returns it. | |||
| data.products[].images[].url | string | No | https://cdn.shopify.com/s/files/1/example.jpg | URL of the image file. | ||
| data.products[].images[].variant_ids | array | No | Ids of the variants this image is attached to. | |||
| data.products[].images[].width | integer | No | 1600 | Image width in pixels. | ||
| data.products[].labels | array | No | new | Badges the storefront shows on the product, for example `new`. | ||
| data.products[].options | array | No | Options the product varies by, such as size or colour. | |||
| data.products[].options[].name | string | No | Size | Option name, for example `Size`. | ||
| data.products[].options[].position | integer | No | 1 | Position of the option on the product, starting at 1. | ||
| data.products[].options[].values | array | No | Values the option can take, for example `S` or `M`. | |||
| data.products[].price | number | No | 98 | Current price in the store's currency. The lowest variant price when variants are listed. | ||
| data.products[].product_type | string | No | Shoes | Product type set by the merchant, for example `Shoes`. | ||
| data.products[].published_at | string | No | Time the record was published, as Shopify returns it. | |||
| data.products[].rating | number | No | 4.2 | Average customer rating shown by the storefront. | ||
| data.products[].rating_count | integer | No | 1549 | Number of customer ratings behind `rating`. | ||
| data.products[].tags | array | No | Tags the merchant attached to the product. | |||
| data.products[].title | string | No | Men's Wool Runners | Product name as shown on the storefront. | ||
| data.products[].updated_at | string | No | Time the record was last updated, as Shopify returns it. | |||
| data.products[].url | string | No | https://www.allbirds.com/products/mens-wool-runners | Storefront page URL of the product. | ||
| data.products[].variants | array | No | Purchasable variants of the product, such as each size and colour. | |||
| data.products[].variants[].available | boolean | No | Whether this variant is currently available to buy. | |||
| data.products[].variants[].barcode | string | No | Barcode of the variant, such as a UPC or EAN. | |||
| data.products[].variants[].compare_at_price | number | No | 120 | Original price before discount, in the store's currency. | ||
| data.products[].variants[].created_at | string | No | Time the record was created, as Shopify returns it. | |||
| data.products[].variants[].featured_image | string | No | URL of the image shown for this variant. | |||
| data.products[].variants[].grams | integer | No | 400 | Weight of the variant in grams. | ||
| data.products[].variants[].id | string | No | 34761278160941 | Shopify variant id. | ||
| data.products[].variants[].inventory_quantity | integer | No | 24 | InventoryQuantity is only populated via the embedded-SSR-JSON fallback transport (see ssr_fallback.go); classic-store responses never set it. | ||
| data.products[].variants[].option1 | string | No | Value of the product's first option for this variant, for example a size. | |||
| data.products[].variants[].option2 | string | No | Value of the product's second option for this variant. | |||
| data.products[].variants[].option3 | string | No | Value of the product's third option for this variant. | |||
| data.products[].variants[].position | integer | No | 1 | Position of the variant in the product's variant list, starting at 1. | ||
| data.products[].variants[].price | number | No | 98 | Current price of the variant in the store's currency. | ||
| data.products[].variants[].product_id | string | No | 6616124981328 | Shopify id of the product the variant belongs to. | ||
| data.products[].variants[].requires_shipping | boolean | No | Whether the variant is a physical item that needs shipping. | |||
| data.products[].variants[].sku | string | No | A123 | Merchant stock keeping unit code of the variant. | ||
| data.products[].variants[].taxable | boolean | No | Whether tax is charged on the variant. | |||
| data.products[].variants[].title | string | No | Natural Black / 10 | Variant name, for example `Natural Black / 10`. | ||
| data.products[].variants[].updated_at | string | No | Time the record was last updated, as Shopify returns it. | |||
| data.products[].vendor | string | No | Allbirds | Brand or vendor name set by the merchant. | ||
| data.source_url | string | No | https://www.allbirds.com | URL the data was read from. | ||
| data.store_url | string | No | https://www.allbirds.com | Base URL of the Shopify storefront that was queried. | ||
| data.transport_mode | string | No | ssr_embedded | ssr_embedded | Set only for headless storefronts that do not expose Shopify's standard catalogue; the value is `ssr_embedded`. Omitted otherwise. | |
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 404 | Not Found | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/shopify/products/mens-wool-runners/recommendations?url=https%3A%2F%2Fwww.allbirds.com&limit=10&intent=related" \
-H "x-api-key: $CRAWLORA_API_KEY"