Skip to main content

Themes

A store's look rests on three choices, the same three tabs as the Themes page of the dashboard (/dashboard/themes): the storefront theme, the theme of the fast-checkout order form on product pages, and the style of the variant picker. GET /v1/themes lists the options of all three choices with a verdict for the store, and one POST call switches each choice. Colours, texts and the other design fields are changed with PATCH /v1/store/design (see Store). For what each theme looks like and what changes for buyers, see the merchant guide to Themes.

Before you start​

  • GET /v1/themes needs store:read. The three switches need store:write and an Idempotency-Key. Merchant keys carry both scopes.
  • Each theme and style has a minimum plan. Plans rank free, pro, unlimited, enterprise, and a plan opens everything the plans below it open. A switch to a theme or style above the store's plan answers 403 plan_required. A paid plan that has expired counts as free.
  • A merchant key belongs to a store on an active Enterprise plan, so every theme and style is open to it. Installed-app tokens work on every plan and meet these limits.
  • A switch is saved as soon as the call answers. There is no confirmation step.
  • The first answer to an Idempotency-Key is replayed for 24 hours, 4xx errors included. After the store's plan changes, send the switch again with a new key. See Idempotency.
  • Every switch is recorded and can be undone with POST /v1/changes/{change_id}/undo: the answer carries its change_id, null in the rare case the switch was saved without an undo record, and GET /v1/changes?entity=store.theme lists the earlier ones. An installed app's token cannot read or undo changes: both answer 403 forbidden (Apps cannot use this endpoint).

GET /v1/themes​

Lists the storefront themes, the fast-checkout form themes and the variant picker styles, each with the plan it needs and whether this store can use it, plus the key of the storefront theme in use. The whole list comes in one answer, with no pagination. A theme or style that can no longer be selected stays in its list with active: false.

Auth: platform key with store:read. This call is not cached: every answer reads the current state.

Request​

curl https://api.dzbuild.app/v1/themes \
-H "Authorization: Bearer $DZ_KEY"

Response 200​

Three storefront themes and two items of each other list are shown. Titles come in the store language, and this store is set to French.

{
"data": {
"current": "starter",
"items": [
{
"key": "starter",
"title": "Starter",
"plan_required": "free",
"active": true,
"color_mode": "light",
"digital_only": false,
"can_use": true,
"current": true
},
{
"key": "digital",
"title": "Digital",
"plan_required": "free",
"active": true,
"color_mode": "dark",
"digital_only": true,
"can_use": true,
"current": false
},
{
"key": "ariana",
"title": "Ariana",
"plan_required": "unlimited",
"active": false,
"color_mode": "dark",
"digital_only": false,
"can_use": false,
"current": false
}
],
"fast_checkout": [
{
"key": "classic",
"title": "Classique",
"plan_required": "free",
"active": true,
"can_use": true,
"current": true
},
{
"key": "stepper",
"title": "Stepper",
"plan_required": "enterprise",
"active": true,
"can_use": false,
"current": false
}
],
"variant_styles": [
{
"key": "default",
"title": "Par défaut",
"plan_required": "free",
"active": true,
"can_use": true,
"current": true
},
{
"key": "lux",
"title": "Luxe",
"plan_required": "enterprise",
"active": true,
"can_use": false,
"current": false
}
]
},
"meta": { "request_id": "...", "api_version": "v1" }
}

Field reference​

FieldTypeNotes
currentstringKey of the theme the store uses.
items[].keystringThe value to send as theme to POST /v1/store/theme.
items[].titlestringThe theme name in the store language: Arabic, or French for a French store.
items[].plan_requiredstringThe lowest plan that can use the theme.
items[].activeboolfalse for a theme that can no longer be selected.
items[].color_modestringlight or dark.
items[].digital_onlybooltrue for a theme made for digital products only. Selecting it changes the store type, as described under POST /v1/store/theme.
items[].can_usebooltrue when the theme is active and the store's plan reaches plan_required.
items[].currentbooltrue for the theme in use.
fast_checkout[].keystringThe value to send as theme to POST /v1/store/fast-checkout-theme.
fast_checkout[].titlestringThe form theme name in the store language.
fast_checkout[].plan_requiredstringThe lowest plan that can use the form theme.
fast_checkout[].activeboolfalse for a form theme that can no longer be selected.
fast_checkout[].can_usebooltrue when the form theme is active and the store's plan reaches plan_required.
fast_checkout[].currentbooltrue for the form theme in use. Every store starts on classic.
variant_styles[].keystringThe value to send as style to POST /v1/store/variant-style. The first item is always default, the standard picker with no added style, which every plan can use and which is current while the store uses it.
variant_styles[].titlestringThe style name in the store language.
variant_styles[].plan_requiredstringThe lowest plan that can use the style.
variant_styles[].activeboolfalse for a style that can no longer be selected.
variant_styles[].can_usebooltrue when the style is active and the store's plan reaches plan_required.
variant_styles[].currentbooltrue for the style in use. A saved style that is no longer active counts as default.

Errors​

The same as GET /v1/store: 401 unauthorized, 402 quota_exceeded, 403 forbidden, 404 not_found and 429 rate_limited. See Errors.

POST /v1/store/theme​

Switches the storefront theme. Only the theme changes: colours, texts and the other design values stay as they are, and the new theme shows the ones it uses. Switching to digital is the exception described below.

Auth: platform key with store:write. Requires Idempotency-Key.

Body​

FieldTypeRequiredNotes
themestringyesA key from GET /v1/themes. Latin letters, digits, _ and -, up to 50 characters.

Switching to digital​

digital is the theme with digital_only: true. Switching to it turns the store into a digital-products store, and the answer carries is_digital: true. Switching a digital store to any other theme turns it back into a physical-products store. The merchant guide to Themes explains what changes for buyers.

The switch to digital also replaces the colours that still hold the stock light values, such as a #ffffff background, with the Digital dark palette. Colours the merchant chose are kept. Undoing the switch puts the earlier theme and those colours back.

Request​

curl -X POST https://api.dzbuild.app/v1/store/theme \
-H "Authorization: Bearer $DZ_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: store-theme-1" \
-d '{"theme": "bloom"}'

Response 200​

{
"data": {
"theme": "bloom",
"is_digital": false,
"change_id": 813
},
"meta": { "request_id": "...", "api_version": "v1" }
}

Through api.dzbuild.app, a GET /v1/store/design sent right after the switch returns the new theme. GET /v1/themes is served fresh too.

Errors​

HTTPCodeCause
400bad_requestThe body is not valid JSON, or Idempotency-Key is missing or malformed.
403forbiddenMissing scope: store:write, or a merchant key whose store is not on an active Enterprise plan.
403plan_requiredThe theme needs a higher plan. The message names that plan and the store's plan.
404theme_not_foundNo active theme has this key.
404store_not_foundThe store was deleted.
422invalid_themetheme is missing, longer than 50 characters, or holds a character other than Latin letters, digits, _ and -.
422idempotency_key_reuseThe same Idempotency-Key was used with another body.

POST /v1/store/fast-checkout-theme​

Switches the look of the fast-checkout order form on product pages. The form's texts, colours and switches, which are fields of PATCH /v1/store/design, stay as they are.

Auth: platform key with store:write. Requires Idempotency-Key.

Body​

FieldTypeRequiredNotes
themestringyesA key from the fast_checkout list of GET /v1/themes. Latin letters, digits, _ and -, up to 50 characters.

Fast-checkout themes​

GET /v1/themes lists these themes in fast_checkout, with the plan each one needs, whether the store can use it and which one is in use; GET /v1/store also returns the one in use as fast_checkout_theme. Every store starts on classic. The merchant guide to Themes describes each one.

Request​

curl -X POST https://api.dzbuild.app/v1/store/fast-checkout-theme \
-H "Authorization: Bearer $DZ_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: store-fc-theme-1" \
-d '{"theme": "stepper"}'

Response 200​

{
"data": {
"fast_checkout_theme": "stepper",
"change_id": 814
},
"meta": { "request_id": "...", "api_version": "v1" }
}

Errors​

HTTPCodeCause
400bad_requestThe body is not valid JSON, or Idempotency-Key is missing or malformed.
403forbiddenMissing scope: store:write, or a merchant key whose store is not on an active Enterprise plan.
403plan_requiredThe theme needs a higher plan than the store's.
404theme_not_foundNo active fast-checkout theme has this key.
404store_not_foundThe store was deleted.
422invalid_themetheme is missing, longer than 50 characters, or holds a character other than Latin letters, digits, _ and -.
422idempotency_key_reuseThe same Idempotency-Key was used with another body.

POST /v1/store/variant-style​

Switches how the variant choices, such as sizes and colours, are drawn on product pages.

Auth: platform key with store:write. Requires Idempotency-Key.

Body​

FieldTypeRequiredNotes
stylestringyesA key from the variant_styles list of GET /v1/themes, up to 50 characters.

Variant styles​

GET /v1/themes lists the styles in variant_styles, with the plan each one needs, whether the store can use it and which one is in use; GET /v1/store also returns the one in use as variant_card_style. Every store starts on default, the standard picker with no added style, which is the first item of the list and which any store can go back to. An unknown or inactive key answers 404 style_not_found; the API never falls back to default on its own.

Request​

curl -X POST https://api.dzbuild.app/v1/store/variant-style \
-H "Authorization: Bearer $DZ_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: store-variant-style-1" \
-d '{"style": "minimal"}'

Response 200​

{
"data": {
"variant_card_style": "minimal",
"change_id": 815
},
"meta": { "request_id": "...", "api_version": "v1" }
}

Errors​

HTTPCodeCause
400bad_requestThe body is not valid JSON, or Idempotency-Key is missing or malformed.
403forbiddenMissing scope: store:write, or a merchant key whose store is not on an active Enterprise plan.
403plan_requiredThe style needs a higher plan than the store's.
404style_not_foundNo active style has this key.
404store_not_foundThe store was deleted.
422invalid_stylestyle is missing, empty or longer than 50 characters.
422idempotency_key_reuseThe same Idempotency-Key was used with another body.