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/themesneedsstore:read. The three switches needstore:writeand anIdempotency-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 answers403 plan_required. A paid plan that has expired counts asfree. - 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-Keyis replayed for 24 hours,4xxerrors 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 itschange_id,nullin the rare case the switch was saved without an undo record, andGET /v1/changes?entity=store.themelists the earlier ones. An installed app's token cannot read or undo changes: both answer403 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
| Field | Type | Notes |
|---|---|---|
current | string | Key of the theme the store uses. |
items[].key | string | The value to send as theme to POST /v1/store/theme. |
items[].title | string | The theme name in the store language: Arabic, or French for a French store. |
items[].plan_required | string | The lowest plan that can use the theme. |
items[].active | bool | false for a theme that can no longer be selected. |
items[].color_mode | string | light or dark. |
items[].digital_only | bool | true for a theme made for digital products only. Selecting it changes the store type, as described under POST /v1/store/theme. |
items[].can_use | bool | true when the theme is active and the store's plan reaches plan_required. |
items[].current | bool | true for the theme in use. |
fast_checkout[].key | string | The value to send as theme to POST /v1/store/fast-checkout-theme. |
fast_checkout[].title | string | The form theme name in the store language. |
fast_checkout[].plan_required | string | The lowest plan that can use the form theme. |
fast_checkout[].active | bool | false for a form theme that can no longer be selected. |
fast_checkout[].can_use | bool | true when the form theme is active and the store's plan reaches plan_required. |
fast_checkout[].current | bool | true for the form theme in use. Every store starts on classic. |
variant_styles[].key | string | The 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[].title | string | The style name in the store language. |
variant_styles[].plan_required | string | The lowest plan that can use the style. |
variant_styles[].active | bool | false for a style that can no longer be selected. |
variant_styles[].can_use | bool | true when the style is active and the store's plan reaches plan_required. |
variant_styles[].current | bool | true 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
| Field | Type | Required | Notes |
|---|---|---|---|
theme | string | yes | A 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
| HTTP | Code | Cause |
|---|---|---|
| 400 | bad_request | The body is not valid JSON, or Idempotency-Key is missing or malformed. |
| 403 | forbidden | Missing scope: store:write, or a merchant key whose store is not on an active Enterprise plan. |
| 403 | plan_required | The theme needs a higher plan. The message names that plan and the store's plan. |
| 404 | theme_not_found | No active theme has this key. |
| 404 | store_not_found | The store was deleted. |
| 422 | invalid_theme | theme is missing, longer than 50 characters, or holds a character other than Latin letters, digits, _ and -. |
| 422 | idempotency_key_reuse | The 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
| Field | Type | Required | Notes |
|---|---|---|---|
theme | string | yes | A 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
| HTTP | Code | Cause |
|---|---|---|
| 400 | bad_request | The body is not valid JSON, or Idempotency-Key is missing or malformed. |
| 403 | forbidden | Missing scope: store:write, or a merchant key whose store is not on an active Enterprise plan. |
| 403 | plan_required | The theme needs a higher plan than the store's. |
| 404 | theme_not_found | No active fast-checkout theme has this key. |
| 404 | store_not_found | The store was deleted. |
| 422 | invalid_theme | theme is missing, longer than 50 characters, or holds a character other than Latin letters, digits, _ and -. |
| 422 | idempotency_key_reuse | The 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
| Field | Type | Required | Notes |
|---|---|---|---|
style | string | yes | A 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
| HTTP | Code | Cause |
|---|---|---|
| 400 | bad_request | The body is not valid JSON, or Idempotency-Key is missing or malformed. |
| 403 | forbidden | Missing scope: store:write, or a merchant key whose store is not on an active Enterprise plan. |
| 403 | plan_required | The style needs a higher plan than the store's. |
| 404 | style_not_found | No active style has this key. |
| 404 | store_not_found | The store was deleted. |
| 422 | invalid_style | style is missing, empty or longer than 50 characters. |
| 422 | idempotency_key_reuse | The same Idempotency-Key was used with another body. |