A valid request URL is required to generate request examples{
"id": "<string>",
"name": "<string>",
"context": "product",
"steps": [
{
"kind": "best_sellers",
"params": {
"freshness_days": 123,
"candidate_pool": 123
},
"filters": [
{
"type": "price",
"min_fraction_of_median": 123,
"max_fraction_of_median": 123
}
],
"limit": 123,
"order_by": {
"kind": "similarity",
"seed": {
"max_seeds": 123,
"weights": {
"product": 123,
"viewed": 123,
"cart": 123
},
"recency_retention": 0
},
"max_distance": 123
}
}
],
"filters": [
{
"type": "price",
"min_fraction_of_median": 123,
"max_fraction_of_median": 123
}
],
"stock_mode": "in_stock",
"limit": 123,
"excluded_product_ids": [
"<string>"
],
"pin_mode": "insert",
"looks": "none",
"custom_rules": [
"<unknown>"
],
"only_show_pinned": true,
"shuffle": true,
"avoid_surfaces": [
"<string>"
]
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}Read one recommendation surface
Returns one saved surface by name: its id, context, steps, filters, limit, exclusions and the read-only serving directives. Call it to inspect a surface before changing it with the PUT on the same path. Read-only.
A valid request URL is required to generate request examples{
"id": "<string>",
"name": "<string>",
"context": "product",
"steps": [
{
"kind": "best_sellers",
"params": {
"freshness_days": 123,
"candidate_pool": 123
},
"filters": [
{
"type": "price",
"min_fraction_of_median": 123,
"max_fraction_of_median": 123
}
],
"limit": 123,
"order_by": {
"kind": "similarity",
"seed": {
"max_seeds": 123,
"weights": {
"product": 123,
"viewed": 123,
"cart": 123
},
"recency_retention": 0
},
"max_distance": 123
}
}
],
"filters": [
{
"type": "price",
"min_fraction_of_median": 123,
"max_fraction_of_median": 123
}
],
"stock_mode": "in_stock",
"limit": 123,
"excluded_product_ids": [
"<string>"
],
"pin_mode": "insert",
"looks": "none",
"custom_rules": [
"<unknown>"
],
"only_show_pinned": true,
"shuffle": true,
"avoid_surfaces": [
"<string>"
]
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}Authorizations
Shopify App Bridge session token of the embedded Depict: Search & Merchandising app. The shop in the token determines the merchant; merchant_id parameters must belong to that shop.
Path Parameters
The surface's URL-safe name.
^[a-z0-9_-]+$Query Parameters
Lite merchant id, e.g. shopify-<shop id>.
Response
The saved surface.
A saved surface. pin_mode, looks, custom_rules, only_show_pinned, shuffle and avoid_surfaces are ops-only serving directives: read-only here; an upsert keeps them (shuffle only while the surface stays live).
Stable uuid; kept across upserts. Pins, metrics and compose address the surface by it.
URL-safe ([a-z0-9_-]+); also the storefront metaobject handle the theme block references.
^[a-z0-9_-]+$Placement: product page (product anchor), category page (collection anchor), or any (no anchor). Per-product recommenders require product.
product, category, any Recommenders in priority order: each fills the slots the ones before it left empty.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
Show child attributes
Show child attributes
Applied to every step's candidates.
Median-relative: 0.5 = half the anchor's (or catalogue's) median price.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
Show child attributes
Show child attributes
Include sold-out products and pins with all; omitted on write resets to in_stock. Generative cross-sell keeps its in-stock pool.
in_stock, all Slots the surface renders.
Products never recommended on this surface.
insert, override none, first, only Was this page helpful?

