Error

A valid request URL is required to generate request examples

{
  "collection_id": "<string>",
  "version": "<string>",
  "version_name": "<string>",
  "sort_order": "ALPHA_ASC",
  "pinned_main_product_ids": [
    "<string>"
  ],
  "collection_boost_rules": [
    {
      "strength": 123,
      "type": "badge",
      "badge": "on_sale",
      "top_n": 123
    }
  ],
  "use_collection_specific_boost_bury": true,
  "unpin_oos": true,
  "main": true,
  "updated_at": "<string>",
  "market_id": "<string>",
  "market_group_id": "<string>",
  "is_market_active": true,
  "scheduled_publish_at": "2023-11-07T05:31:56Z",
  "scheduled_by_email": "<string>",
  "metafield_sort": {
    "key": "<string>",
    "type": "number_integer"
  },
  "active_attachment_ids": [
    "<string>"
  ]
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>",
  "code": "product_required",
  "product": "search",
  "limit": 123
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

API Reference

Create or update a collection version

Saves the body as a version of the collection without publishing it (publishing is PUT …/publish_version/); version null or unknown creates a new version. Side effects: writes the version row, and when is_market_active is true deactivates the other versions of the same market or market group; then triggers a Shopify order sync-back (its failure does not fail the save). Setting is_market_active true makes the version live for its market, so it requires collection versions in the plan like publishing does (402 otherwise); drafting never does. Returns the version as stored.

PUT

collections

{collection_id}

update_version

Error

A valid request URL is required to generate request examples

{
  "collection_id": "<string>",
  "version": "<string>",
  "version_name": "<string>",
  "sort_order": "ALPHA_ASC",
  "pinned_main_product_ids": [
    "<string>"
  ],
  "collection_boost_rules": [
    {
      "strength": 123,
      "type": "badge",
      "badge": "on_sale",
      "top_n": 123
    }
  ],
  "use_collection_specific_boost_bury": true,
  "unpin_oos": true,
  "main": true,
  "updated_at": "<string>",
  "market_id": "<string>",
  "market_group_id": "<string>",
  "is_market_active": true,
  "scheduled_publish_at": "2023-11-07T05:31:56Z",
  "scheduled_by_email": "<string>",
  "metafield_sort": {
    "key": "<string>",
    "type": "number_integer"
  },
  "active_attachment_ids": [
    "<string>"
  ]
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>",
  "code": "product_required",
  "product": "search",
  "limit": 123
}

{
  "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

collection_id

string

required

Numeric Shopify collection id.

Query Parameters

merchant_id

string

required

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

Body

application/json

sort_order

enum<string>

required

How Depict sorts the collection. MANUAL keeps the pinned order; METAFIELD_ASC/DESC sort by the version's metafield_sort key.

Available options:

ALPHA_ASC,

ALPHA_DESC,

BEST_SELLING,

BEST_SELLING_BY_REVENUE,

MOST_RELEVANT,

TRENDING,

TRENDING_BY_REVENUE,

CREATED,

CREATED_DESC,

PRICE_ASC,

PRICE_DESC,

STOCK_DESC,

CLICKS_DESC,

METAFIELD_ASC,

METAFIELD_DESC,

MANUAL

pinned_main_product_ids

string[]

required

Product ids pinned to the top, in order.

collection_boost_rules

object[]

required

A merchant-wide rule that moves matching products up (boost) or down (bury) in every automatically sorted collection. type selects how products match.

Option 1
Option 2
Option 3
Option 4

Show child attributes

use_collection_specific_boost_bury

boolean

required

unpin_oos

boolean

required

version_name

string | null

required

version

string<uuid> | null

required

The version to update; null creates a new version.

metafield_sort

object | null

Required exactly when sort_order is METAFIELD_ASC/METAFIELD_DESC.

Show child attributes

active_attachment_ids

string<uuid>[] | null

Null/absent leaves the stored attachments unchanged.

market_id

string | null

market_group_id

string | null

is_market_active

boolean | null

Response

The saved version.

collection_id

string

required

Numeric Shopify collection id.

version

string

required

Version UUID.

version_name

string | null

required

sort_order

enum<string>

required

How Depict sorts the collection. MANUAL keeps the pinned order; METAFIELD_ASC/DESC sort by the version's metafield_sort key.

Available options:

ALPHA_ASC,

ALPHA_DESC,

BEST_SELLING,

BEST_SELLING_BY_REVENUE,

MOST_RELEVANT,

TRENDING,

TRENDING_BY_REVENUE,

CREATED,

CREATED_DESC,

PRICE_ASC,

PRICE_DESC,

STOCK_DESC,

CLICKS_DESC,

METAFIELD_ASC,

METAFIELD_DESC,

MANUAL

pinned_main_product_ids

string[]

required

collection_boost_rules

object[]

required

A merchant-wide rule that moves matching products up (boost) or down (bury) in every automatically sorted collection. type selects how products match.

Option 1
Option 2
Option 3
Option 4

Show child attributes

use_collection_specific_boost_bury

boolean

required

unpin_oos

boolean

required

main

boolean

required

This is the collection's published (main) version.

updated_at

string

required

Naive UTC.

market_id

string | null

required

Set when the version targets one Shopify market.

market_group_id

string | null

required

Set when the version targets a market group.

is_market_active

boolean

required

Published to its market / market group.

scheduled_publish_at

string<date-time> | null

required

UTC ISO timestamp (Z) the cron will publish it at; null when unscheduled.

scheduled_by_email

string | null

required

metafield_sort

object | null

required

Show child attributes

active_attachment_ids

string[]

required