Journal des versions de l'API

Notifications de mise à jour de produit - octobre 2026

Informez par e-mail les acheteurs d'un produit qu'il a été mis à jour — la campagne qu'un marchand lance avec Notifier les clients sur la page d'un produit — depuis votre propre système. Additif au contrat v1. Disponible sur toutes les formules payantes.

• Nouveau POST /products/{shopify_product_id}/notifications : met en file d'attente une campagne (202) pour chaque acheteur des mappings téléchargeables du produit ou, avec variant_ids, des mappings desservant ces variantes. message facultatif en texte brut de 2 000 caractères maximum avec {customer.first_name}, {shop.name}, {product.title} et {product.metafields.<namespace>.<key>} ; aucun lien. dry_run exécute toutes les vérifications et renvoie les compteurs, l'objet et la note rendue sans envoyer (200 ; utilisez une Idempotency-Key neuve par simulation). Coûte 10 jetons de limite de débit.
• Nouveau GET /notifications/{notificationId} : le statut de la campagne, les compteurs, waiting_for_archive et un vocabulaire error fermé ; completed avec partial: true lorsque certains envois ont échoué. Les campagnes lancées dans l'application apparaissent aussi.
• Nouveau POST /notifications/{notificationId}/cancel : annule une campagne en file d'attente (200). La limite de 7 jours du produit est conservée, exactement comme une annulation dans l'application.
• Nouvel objet facultatif notify_customers sur POST /mappings et PUT /mappings/{id} : met en file d'attente une notification pour les acheteurs du mapping écrit une fois l'écriture validée. Une note qui enfreint une règle portant sur son propre texte (vide, trop longue, une variable incorrecte, plus de cinq métachamps, un lien dans le texte) donne 422 invalid_message sans rien écrire ; un problème de métachamp et tout autre refus sont signalés dans le nouveau champ data.notification (created: false, error), jamais sous forme de 4xx. data.notification n'est présent que lorsque l'indicateur a été envoyé ; les réponses existantes sont inchangées.
• Une campagne par produit tous les 7 jours, toutes variantes et toutes sources confondues, et aucune tant qu'une autre est encore en file d'attente ou en cours d'envoi : 429 notification_cooldown avec Retry-After (jusqu'à sept jours) et error.details.next_available_at. Ce n'est pas le seau à jetons — ne réessayez pas automatiquement ; planifiez le prochain appel à next_available_at.
• 5 campagnes au maximum par boutique en file d'attente ou en cours d'envoi en même temps, tous produits et toutes sources confondus : une sixième donne 429 too_many_active_notifications avec error.details.limit et error.details.active_notification_ids, sans Retry-After. Réessayez une fois que l'une d'elles est terminée. Une simulation est refusée de la même manière ; lors d'une écriture de mapping, le refus est signalé dans data.notification.
• Un seul e-mail de mise à jour de produit par acheteur, par boutique et par période de 24 heures, toutes campagnes confondues : un acheteur qui en a déjà reçu un est ignoré au moment où la campagne envoie. Les acheteurs ignorés ne figurent ni dans sent_count, ni dans failed_count, ni dans suppressed_count. Une campagne qui a ignoré tous les acheteurs se termine en failed avec error: recipients_recently_notified et ne consomme pas les 7 jours du produit.
• Avant chaque lot de 500 e-mails au maximum, la campagne vérifie à nouveau la boutique et s'arrête si l'abonnement ou la formule payante a expiré, si les e-mails aux clients ont été désactivés, si l'envoi a été suspendu ou si Alva a désactivé les notifications. Arrêtée avant qu'aucun acheteur n'ait reçu d'e-mail, elle est failed (plan_required, email_disabled, notifications_suspended ou notifications_switched_off) et libère les 7 jours ; arrêtée plus tard, elle est completed avec partial: true. Une campagne dont tous les envois ont échoué est failed avec nothing_sent et libère aussi les 7 jours ; une campagne qui n'avait plus personne à qui écrire au moment de l'envoi est failed avec no_eligible_recipients et les libère également.
• Une campagne dont le mapping ciblé a une régénération ZIP en cours l'attend (waiting_for_archive: true ; seul un mapping qui livre une archive ZIP fait attendre une campagne) ; une régénération échouée, ou qui reste 60 minutes sans progresser pendant la génération (6 heures tant qu'elle attend encore de démarrer ou d'être relancée), décomptées à partir de la régénération, et non de la création de la campagne, fait échouer la campagne avec zéro envoi et libère la limite.
• Huit nouveaux codes d'erreur : 403 notifications_suspended, 404 notification_not_found, 409 notification_not_cancellable, 422 invalid_message, 422 no_downloadable_content, 422 no_eligible_recipients, 429 notification_cooldown, 429 too_many_active_notifications. mapping_not_found et multiple_mappings_match gagnent error.details.unresolved_variant_ids / ambiguous_variant_ids sur cet endpoint.

Mise à jour de l'accès - septembre 2026

L'accès à l'API n'est plus soumis à approbation.

• Toutes les formules payantes (Basic, Pro et Enterprise) peuvent utiliser l'API. Créez des clés dans l'application sous Paramètres → API keys ; il n'y a rien à demander.
• Avec la formule Free, l'onglet API keys est masqué et les clés existantes renvoient 402 plan_required jusqu'à ce que la boutique passe à une formule payante.

Mise à jour v1 - juillet 2026

Ajouts additifs de codes d'erreur et de champs de réponse au contrat v1 existant.

• Nouvelle erreur 422 withdrawal_consent_required sur l'endpoint download-urls des commandes : renvoyée lorsque la boutique a activé le consentement au droit de rétractation UE et que la commande n'a pas encore d'enregistrement de consentement ; les URL de téléchargement sont émises dès que le client donne son consentement.
• Nouvelle erreur 422 key_limit_reached à la création de clés API : une boutique peut détenir au plus 25 clés API actives ; révoquez-en une d'abord.
• Nouvelle erreur 409 delivery_not_yet_released sur les endpoints download-urls et resend des commandes : renvoyée lorsque le produit a un délai de livraison du téléchargement configuré et que les fichiers de l'acheteur ne sont pas encore débloqués. Aucune URL de téléchargement n'est émise et aucun e-mail n'est envoyé tant que le délai n'est pas écoulé.
• Nouvel objet error.details dans l'enveloppe d'erreur : présent uniquement sur les codes qui transportent un contexte sûr pour l'appelant. Aujourd'hui, delivery_not_yet_released est le seul à le produire, et il contient release_at, l'instant ISO 8601 auquel les téléchargements se débloquent. Considérez cet objet comme ouvert : de nouvelles clés peuvent apparaître sans changement de version majeure.
• Nouveaux champs delivery_pending et release_at sur l'objet achat du statut de commande : delivery_pending vaut true tant qu'un achat est encore retenu par un délai de livraison du téléchargement, et release_at est l'instant ISO 8601 du déblocage, ou null lorsque rien n'est en attente.
• L'endpoint grant-downloads libère désormais immédiatement les achats retenus de la commande, ce qui permet à un marchand de passer outre un délai de livraison du téléchargement via l'API.

v1.0.0 - juin 2026

Surface initiale de l'API pilote, en accès sur approbation uniquement.

• Clés d'API pour les boutiques approuvées.
• Clés d'idempotence requises sur les requêtes d'écriture.
• Import d'assets par URL distante, téléversements directs, liste des assets, mises à jour d'assets et suppression d'assets.
• Catégories à plat, mappings de produits, packs et étiquettes de clés de licence.
• Attributions de commandes qui rendent les téléchargements mappés visibles dans les comptes clients Shopify.
• Contrôles d'accès aux commandes : révoquer, restaurer, accorder des téléchargements et renvoyer l'e-mail.
• Endpoints de statut des tâches et des commandes.
• Téléchargements de la spécification OpenAPI et de la collection Postman.

Politique de versionnage

Le contrat v1 est additif uniquement : de nouveaux endpoints, des champs optionnels et de nouveaux codes d'erreur peuvent être ajoutés. Les changements incompatibles utiliseront un futur chemin /api/v2.