Schéma des promotions — ACP

Les promotions d'un flux se gèrent exclusivement via GET/PATCH /product_feeds/{id}/promotions — aucune promotion ne peut passer par le fichier plat, qui n'en comporte aucun champ. GET retourne le tableau Promotion[] du flux ; PATCH upserte des promotions appariées par id, celles non incluses restant inchangées, avec un objet d'acceptation (id, accepted) en retour.

La structure d'une promotion

Un objet Promotion combine un id et un title (requis), une période active (active_period, type DateTimeRange avec start_time/end_time, requise) et un ou plusieurs avantages (benefits, requis) — trois champs sans lesquels la promotion n'est pas valide. description, status et url restent optionnels ; applies_to (ProductTarget[]) cible optionnellement des produits ou variantes précis via product_id et variant_ids. Le statut (PromotionStatus) prend les valeurs draft, scheduled, active, expired ou disabled, sans que la documentation précise si la transition entre ces états est automatique en fonction de active_period ou nécessite une mise à jour manuelle par PATCH.

Chaque avantage de benefits appartient à l'un de trois types, distingués par un champ type :

Type	Champ de valeur
AmountOffBenefit (type: amount_off)	amount_off : objet Price (amount, currency).
PercentOffBenefit (type: percent_off)	percent_off : nombre.
FreeShippingBenefit (type: free_shipping)	aucun autre champ.

Mise en pratique

1. Toujours renseigner active_period et benefits : ce sont, avec id et title, les seuls champs requis d'une promotion.
2. Choisir le type d'avantage adapté (amount_off, percent_off, free_shipping) plutôt que de tenter de les combiner dans un seul objet.
3. Cibler explicitement via applies_to dès qu'une promotion ne doit pas s'appliquer à l'ensemble du catalogue, la portée par défaut sans ciblage n'étant pas précisée par la documentation disponible.

Erreurs à éviter

Omettre active_period ou benefits en les traitant comme les autres champs optionnels du schéma est l'erreur la plus directe : la promotion n'est alors pas valide. Supposer qu'un status se met à jour tout seul à l'expiration d'active_period n'est pas confirmé par la documentation disponible — mieux vaut vérifier explicitement plutôt que présumer.

Ce qu'il faut retenir

Une promotion valide repose sur trois champs non négociables — identifiant, période active, avantages — et n'existe que du côté API : aucune méthode alternative ne permet de les fournir par fichier. Le cycle de vie exact des statuts et la portée par défaut d'un ciblage absent restent des points à vérifier avant une implémentation en production.