Error

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>"
  ],
  "ingestion": {
    "merchantId": "<string>",
    "status": "started",
    "instanceId": "<string>"
  }
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

API Reference

Create or replace a recommendation surface

Creates the surface named in the path, or replaces its editable fields (context, steps, filters, limit, exclusions) if it exists; an existing surface keeps its id and serving directives. The body’s name must equal the path’s. Side effects: writes the storefront metaobject in Shopify, then the recommendations config; deletes pins whose anchor type the new context no longer admits; queues a background recompute of this surface and replicates the change to linked stores. Requires recommendations in the store’s plan (402 otherwise),. Changed metafield keys request full ingestion after saving. Returns the saved surface.

PUT

recommendations

surfaces

{surface_name}

Error

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>"
  ],
  "ingestion": {
    "merchantId": "<string>",
    "status": "started",
    "instanceId": "<string>"
  }
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

Authorizations

Authorization

string

header

required

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

surface_name

string

required

The surface's URL-safe name.

Pattern: ^[a-z0-9_-]+$

Query Parameters

merchant_id

string

required

Lite merchant id, e.g. shopify-<shop id>.

Body

application/json

name

string

required

URL-safe ([a-z0-9_-]+); also the storefront metaobject handle the theme block references.

Pattern: ^[a-z0-9_-]+$

context

enum<string>

required

Placement: product page (product anchor), category page (collection anchor), or any (no anchor). Per-product recommenders require product.

Available options:

product,

category,

any

steps

object[]

required

Recommenders in priority order: each fills the slots the ones before it left empty.

Show child attributes

filters

object[]

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

stock_mode

enum<string>

default:in_stock

Include sold-out products and pins with all; omitted on write resets to in_stock. Generative cross-sell keeps its in-stock pool.

Available options:

in_stock,

all

limit

integer

default:25

Slots the surface renders.

excluded_product_ids

string[]

Products never recommended on this surface.

Response

The saved surface, with ingestion admission when metafield keys changed.

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).

string

required

Stable uuid; kept across upserts. Pins, metrics and compose address the surface by it.

name

string

required

URL-safe ([a-z0-9_-]+); also the storefront metaobject handle the theme block references.

Pattern: ^[a-z0-9_-]+$

context

enum<string>

required

Placement: product page (product anchor), category page (collection anchor), or any (no anchor). Per-product recommenders require product.

Available options:

product,

category,

any

steps

object[]

required

Recommenders in priority order: each fills the slots the ones before it left empty.

Show child attributes

filters

object[]

required

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

stock_mode

enum<string>

required

Include sold-out products and pins with all; omitted on write resets to in_stock. Generative cross-sell keeps its in-stock pool.

Available options:

in_stock,

all

limit

integer

required

Slots the surface renders.

excluded_product_ids

string[]

required

Products never recommended on this surface.

pin_mode

enum<string>

required

Available options:

insert,

override

looks

enum<string>

required

Available options:

none,

first,

only

custom_rules

any[]

required

only_show_pinned

boolean

required

shuffle

boolean

required

avoid_surfaces

string[]

required

ingestion

object

Option 1
Option 2

Show child attributes

Overview

Search & Merchandising API

Create or replace a recommendation surface

Authorizations

Path Parameters

Query Parameters

Body

Response