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

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.