Error

A valid request URL is required to generate request examples

{
  "confirmation_url": "<string>",
  "change": "subscribe",
  "applies": "immediately",
  "trial_days": 123,
  "app_subscription_id": "<string>",
  "plan": {
    "plan_id": "<string>",
    "display_name": "<string>",
    "products": [
      "search"
    ],
    "size": "s"
  }
}

{
  "detail": "<string>",
  "code": "plan_not_found",
  "active": 123,
  "kept": 123,
  "max": 123
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>",
  "code": "plan_not_found",
  "active": 123,
  "kept": 123,
  "max": 123
}

{
  "detail": "<string>",
  "code": "plan_not_found",
  "active": 123,
  "kept": 123,
  "max": 123
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

API Reference

Subscribe to, upgrade or downgrade to a plan (products + size)

Resolves the selection to a catalogue plan and creates a pending Shopify app subscription replacing the current one; returns the confirmation URL the merchant must open to approve it. Nothing is billed or changed until they approve, except that a downgrade to a plan without Merchandising deactivates the collections not in keep_collection_ids. Upgrades and lateral moves apply immediately (prorated), downgrades at the next billing cycle. See GET /settings/subscription/plans for what can be bought.

POST

settings

subscription

Error

A valid request URL is required to generate request examples

{
  "confirmation_url": "<string>",
  "change": "subscribe",
  "applies": "immediately",
  "trial_days": 123,
  "app_subscription_id": "<string>",
  "plan": {
    "plan_id": "<string>",
    "display_name": "<string>",
    "products": [
      "search"
    ],
    "size": "s"
  }
}

{
  "detail": "<string>",
  "code": "plan_not_found",
  "active": 123,
  "kept": 123,
  "max": 123
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>",
  "code": "plan_not_found",
  "active": 123,
  "kept": 123,
  "max": 123
}

{
  "detail": "<string>",
  "code": "plan_not_found",
  "active": 123,
  "kept": 123,
  "max": 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.

Query Parameters

merchant_id

string

required

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

Body

application/json

products

enum<string>[]

required

The paid products wanted (duplicates ignored). Never empty: DELETE /settings/subscription is the way to the free tier.

Minimum array length: 1

Available options:

search,

recs,

vm

size

enum<string>

required

Available options:

s,

m,

l

interval

enum<string>

required

Available options:

EVERY_30_DAYS,

ANNUAL

return_url

string<uri>

required

Where Shopify sends the merchant after they approve or decline the charge.

keep_collection_ids

string[]

Only read when the target plan lacks Merchandising: the collections that stay active (at most 3). Omitted = keep everything, allowed only when the active set already fits.

Minimum string length: 1

Pattern: ^[^,]*$

discount

object | null

Superuser sessions only; a merchant session sending one is 403.

Show child attributes

Response

The pending change and its confirmation URL.

confirmation_url

string

required

Send the merchant here to approve the charge in Shopify.

change

enum<string>

required

Available options:

subscribe,

upgrade,

downgrade,

lateral

applies

enum<string>

required

Available options:

immediately,

next_billing_cycle

trial_days

integer

required

app_subscription_id

string | null

required

plan

object

required

Show child attributes