L'apparence d'une boutique repose sur trois choix, les trois onglets de la page Thèmes du tableau de bord (/dashboard/themes) : le thème de la boutique, le thème du formulaire de commande Fast Checkout sur les pages produit, et le style du sélecteur de variantes. GET /v1/themes liste les options des trois choix avec un verdict pour la boutique, et un appel POST change chacun d'eux. Les couleurs, les textes et les autres champs de design se modifient avec PATCH /v1/store/design (voir Boutique). Pour l'aspect de chaque thème et ce qui change pour les acheteurs, voir le guide marchand Thèmes.

Avant de commencer

GET /v1/themes demande store:read. Les trois changements demandent store:write et une Idempotency-Key. Les clés marchand ont les deux scopes.
Chaque thème et chaque style a un plan minimum. Les plans se classent free, pro, unlimited, enterprise, et un plan ouvre tout ce qu'ouvrent les plans en dessous. Passer à un thème ou un style au-dessus du plan de la boutique répond 403 plan_required. Un plan payant expiré compte comme free.
Une clé marchand appartient à une boutique sur un plan Enterprise actif : tous les thèmes et styles lui sont ouverts. Les jetons d'application installée fonctionnent avec tous les plans et sont soumis à ces limites.
Un changement est enregistré dès que l'appel répond. Il n'y a pas d'étape de confirmation.
La première réponse à une Idempotency-Key est rejouée pendant 24 heures, erreurs 4xx comprises. Après un changement de plan de la boutique, renvoyez le changement avec une nouvelle clé. Voir Idempotence.
Chaque changement est enregistré et peut être annulé avec POST /v1/changes/{change_id}/undo : la réponse porte son change_id, null dans le cas rare où le changement est enregistré sans trace d'annulation, et GET /v1/changes?entity=store.theme liste les précédents. Le jeton d'une application installée ne peut ni lire ni annuler les changements : les deux répondent 403 forbidden (Apps cannot use this endpoint).

GET /v1/themes

Liste les thèmes de boutique, les thèmes du formulaire Fast Checkout et les styles du sélecteur de variantes, chacun avec le plan qu'il demande et si cette boutique peut l'utiliser, plus la clé du thème de boutique utilisé. La liste entière arrive en une réponse, sans pagination. Un thème ou un style qui ne peut plus être choisi reste dans sa liste avec active: false.

Auth : clé plateforme avec store:read. Cet appel n'est pas mis en cache : chaque réponse lit l'état actuel.

Requête

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

Réponse 200

Trois thèmes de boutique et deux éléments de chaque autre liste sont montrés. Les titres arrivent dans la langue de la boutique, et cette boutique est réglée en français.

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

Référence des champs

Champ	Type	Notes
`current`	string	Clé du thème utilisé par la boutique.
`items[].key`	string	La valeur à envoyer dans `theme` à `POST /v1/store/theme`.
`items[].title`	string	Le nom du thème dans la langue de la boutique : arabe, ou français pour une boutique en français.
`items[].plan_required`	string	Le plan le plus bas qui peut utiliser le thème.
`items[].active`	bool	`false` pour un thème qui ne peut plus être choisi.
`items[].color_mode`	string	`light` ou `dark`.
`items[].digital_only`	bool	`true` pour un thème réservé aux produits digitaux. Le choisir change le type de la boutique, comme décrit sous `POST /v1/store/theme`.
`items[].can_use`	bool	`true` quand le thème est actif et que le plan de la boutique atteint `plan_required`.
`items[].current`	bool	`true` pour le thème utilisé.
`fast_checkout[].key`	string	La valeur à envoyer dans `theme` à `POST /v1/store/fast-checkout-theme`.
`fast_checkout[].title`	string	Le nom du thème de formulaire dans la langue de la boutique.
`fast_checkout[].plan_required`	string	Le plan le plus bas qui peut utiliser le thème de formulaire.
`fast_checkout[].active`	bool	`false` pour un thème de formulaire qui ne peut plus être choisi.
`fast_checkout[].can_use`	bool	`true` quand le thème de formulaire est actif et que le plan de la boutique atteint `plan_required`.
`fast_checkout[].current`	bool	`true` pour le thème de formulaire utilisé. Chaque boutique démarre sur `classic`.
`variant_styles[].key`	string	La valeur à envoyer dans `style` à `POST /v1/store/variant-style`. Le premier élément est toujours `default`, le sélecteur standard sans style ajouté, que tous les plans peuvent utiliser et qui est `current` tant que la boutique l'utilise.
`variant_styles[].title`	string	Le nom du style dans la langue de la boutique.
`variant_styles[].plan_required`	string	Le plan le plus bas qui peut utiliser le style.
`variant_styles[].active`	bool	`false` pour un style qui ne peut plus être choisi.
`variant_styles[].can_use`	bool	`true` quand le style est actif et que le plan de la boutique atteint `plan_required`.
`variant_styles[].current`	bool	`true` pour le style utilisé. Un style enregistré qui n'est plus actif compte comme `default`.

Erreurs

Les mêmes que GET /v1/store : 401 unauthorized, 402 quota_exceeded, 403 forbidden, 404 not_found et 429 rate_limited. Voir Erreurs.

POST /v1/store/theme

Change le thème de la boutique. Seul le thème change : les couleurs, les textes et les autres valeurs de design restent tels quels, et le nouveau thème affiche ceux qu'il utilise. Passer à digital est l'exception décrite plus bas.

Auth : clé plateforme avec store:write. Nécessite Idempotency-Key.

Corps

Champ	Type	Requis	Notes
`theme`	string	oui	Une `key` de `GET /v1/themes`. Lettres latines, chiffres, `_` et `-`, jusqu'à 50 caractères.

Passer à digital

digital est le thème qui porte digital_only: true. Y passer transforme la boutique en boutique de produits digitaux, et la réponse porte is_digital: true. Passer une boutique digitale à n'importe quel autre thème la ramène en boutique de produits physiques. Le guide marchand Thèmes explique ce qui change pour les acheteurs.

Le passage à digital remplace aussi les couleurs encore sur les valeurs claires d'origine, comme un fond #ffffff, par la palette sombre de Digital. Les couleurs choisies par le marchand sont gardées. Annuler le changement remet le thème précédent et ces couleurs.

Requête

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"}'

Réponse 200

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

Via api.dzbuild.app, un GET /v1/store/design envoyé juste après le changement renvoie le nouveau thème. GET /v1/themes est servi à neuf lui aussi.

Erreurs

HTTP	Code	Cause
400	`bad_request`	Le corps n'est pas un JSON valide, ou `Idempotency-Key` manque ou est mal formée.
403	`forbidden`	`Missing scope: store:write`, ou clé du marchand dont la boutique n'a pas de plan Enterprise actif.
403	`plan_required`	Le thème demande un plan plus élevé. Le message nomme ce plan et celui de la boutique.
404	`theme_not_found`	Aucun thème actif ne porte cette clé.
404	`store_not_found`	La boutique a été supprimée.
422	`invalid_theme`	`theme` manque, dépasse 50 caractères ou contient un caractère autre que des lettres latines, des chiffres, `_` et `-`.
422	`idempotency_key_reuse`	La même `Idempotency-Key` a été utilisée avec un autre corps.

POST /v1/store/fast-checkout-theme

Change l'apparence du formulaire de commande Fast Checkout sur les pages produit. Les textes, les couleurs et les options du formulaire, qui sont des champs de PATCH /v1/store/design, restent tels quels.

Auth : clé plateforme avec store:write. Nécessite Idempotency-Key.

Corps

Champ	Type	Requis	Notes
`theme`	string	oui	Une `key` de la liste `fast_checkout` de `GET /v1/themes`. Lettres latines, chiffres, `_` et `-`, jusqu'à 50 caractères.

Thèmes Fast Checkout

GET /v1/themes liste ces thèmes dans fast_checkout, avec le plan que demande chacun, si la boutique peut l'utiliser et celui qui est utilisé ; GET /v1/store renvoie aussi celui qui est utilisé dans fast_checkout_theme. Chaque boutique démarre sur classic. Le guide marchand Thèmes décrit chacun d'eux.

Requête

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"}'

Réponse 200

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

Erreurs

HTTP	Code	Cause
400	`bad_request`	Le corps n'est pas un JSON valide, ou `Idempotency-Key` manque ou est mal formée.
403	`forbidden`	`Missing scope: store:write`, ou clé du marchand dont la boutique n'a pas de plan Enterprise actif.
403	`plan_required`	Le thème demande un plan plus élevé que celui de la boutique.
404	`theme_not_found`	Aucun thème Fast Checkout actif ne porte cette clé.
404	`store_not_found`	La boutique a été supprimée.
422	`invalid_theme`	`theme` manque, dépasse 50 caractères ou contient un caractère autre que des lettres latines, des chiffres, `_` et `-`.
422	`idempotency_key_reuse`	La même `Idempotency-Key` a été utilisée avec un autre corps.

POST /v1/store/variant-style

Change la façon dont les choix de variantes, comme les tailles et les couleurs, s'affichent sur les pages produit.

Auth : clé plateforme avec store:write. Nécessite Idempotency-Key.

Corps

Champ	Type	Requis	Notes
`style`	string	oui	Une `key` de la liste `variant_styles` de `GET /v1/themes`, jusqu'à 50 caractères.

Styles de variantes

GET /v1/themes liste les styles dans variant_styles, avec le plan que demande chacun, si la boutique peut l'utiliser et celui qui est utilisé ; GET /v1/store renvoie aussi celui qui est utilisé dans variant_card_style. Chaque boutique démarre sur default, le sélecteur standard sans style ajouté, qui est le premier élément de la liste et auquel toute boutique peut revenir. Une clé inconnue ou inactive répond 404 style_not_found ; l'API ne revient jamais d'elle-même à default.

Requête

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"}'

Réponse 200

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

Erreurs

HTTP	Code	Cause
400	`bad_request`	Le corps n'est pas un JSON valide, ou `Idempotency-Key` manque ou est mal formée.
403	`forbidden`	`Missing scope: store:write`, ou clé du marchand dont la boutique n'a pas de plan Enterprise actif.
403	`plan_required`	Le style demande un plan plus élevé que celui de la boutique.
404	`style_not_found`	Aucun style actif ne porte cette clé.
404	`store_not_found`	La boutique a été supprimée.
422	`invalid_style`	`style` manque, est vide ou dépasse 50 caractères.
422	`idempotency_key_reuse`	La même `Idempotency-Key` a été utilisée avec un autre corps.