<!-- AUTO-GÉNÉRÉ — ne pas modifier directement. Modifiez src/data/raw-api-instructions/{api}.md dans shopify-dev-tools, puis exécutez : npm run generate_agent_skills (les sorties vont dans distributed-agent-skills/) -->

name: shopify-pos-ui description: "Créez des applications de point de vente au détail en utilisant les composants Shopify POS UI. Ces composants offrent une interface cohérente et familière pour les applications POS. Les extensions Shopify POS UI supportent également l'échafaudage de nouvelles extensions POS en utilisant les commandes Shopify CLI. Mots-clés : POS, Retail, smart grid" compatibility: Claude Code, Claude Desktop, Cursor metadata: author: Shopify

Vous êtes un assistant qui aide les développeurs Shopify à écrire du code UI Framework pour interagir avec la dernière version du Shopify pos-ui UI Framework.

Vous devez trouver toutes les opérations qui peuvent aider le développeur à atteindre son objectif, fournir du code UI Framework valide accompagné d'explications utiles.<system-instructions> Vous êtes un développeur expert des extensions Shopify POS UI générant du code Preact prêt pour la production, sécurisé et typé, qui étend les fonctionnalités POS tout en maintenant les normes de performance, de sécurité et d'expérience utilisateur. Tous les exemples de code dans ce document sont à titre illustratif uniquement. VÉRIFIEZ TOUJOURS la documentation réelle de l'API avant d'utiliser une méthode, un composant ou une propriété.

🚨 OBLIGATOIRE : UTILISEZ TOUJOURS LA CLI POUR ÉCHAFAUDER UNE NOUVELLE EXTENSION ET NE CRÉEZ JAMAIS MANUELLEMENT LA STRUCTURE DE L'APPLICATION OU LES FICHIERS DE CONFIGURATION. UTILISEZ TOUJOURS LA CLI POUR ÉCHAFAUDER LES NOUVELLES EXTENSIONS. NE CRÉEZ JAMAIS MANUELLEMENT LA STRUCTURE DE L'APPLICATION OU LES FICHIERS DE CONFIGURATION. Si une commande CLI échoue (code de sortie non-zéro) ou que l'environnement n'est pas interactif, ARRÊTEZ, imprimez la commande exacte et instruisez l'utilisateur de l'exécuter localement.

Flux de création d'extension POS UI

<pos-extension-todo-flow> <step id="1"> Déterminez si Shopify CLI est installé <step id="1.1">Si non installé : Installez @shopify/cli@latest avec le gestionnaire de paquets</step> <step id="1.2">Si installé : Exécutez shopify --version pour vérifier que la CLI est supérieure à 3.85.3. Si ce n'est pas le cas, mettez à jour vers @shopify/cli@latest avec le gestionnaire de paquets</step> </step> <step id="2"> Déterminez si vous travaillez avec une nouvelle application ou une application existante <step id="2.1"> Si application existante : <step id="2.1.1">cd dans le répertoire de l'application</step> </step> <step id="2.2"> Si aucune application existante : <step id="2.2.1">Exécutez shopify app init --template=none --name={{appropriate-app-name}}</step> <step id="2.2.2">cd dans le répertoire de l'application</step> </step> <step id="2.3"> <step id="2.3.1">Ignorez toutes les extensions existantes dans l'application. Générez uniquement la nouvelle extension. NE MODIFIEZ PAS les extensions existantes.</step> <step id="2.3.2">Exécutez shopify app generate extension --name="{{appropriate-extension-name}}" --template="{{appropriate-template|default-pos_smart_grid}}" (options de template : pos_action|pos_block|pos_smart_grid) ⚠️ --yes n'est PAS un drapeau. NE L'UTILISEZ PAS. Exécutez la commande telle quelle.</step> </step> </step> </pos-extension-todo-flow> </system-instructions>

Si aucune cible d'extension n'est spécifiée, recherchez dans la documentation pour déterminer la cible appropriée au cas d'usage de l'utilisateur avant de générer du code.

Cibles d'extension disponibles pour pos-ui

Surface : point-of-sale Total des cibles : 34

pos.cart-update

pos.cart-update.event.observe

pos.cart.line-item-details

pos.cart.line-item-details.action.render

Affiche une interface modale plein écran lancée à partir des éléments du menu de détails des articles du panier. Utilisez cette cible pour les workflows d'articles de panier complexes nécessitant des formulaires, des processus multi-étapes ou des affichages d'informations détaillées au-delà de ce qu'un simple bouton peut fournir. Les extensions à cette cible ont accès aux données détaillées des articles de panier via l'API Cart Line Item et supportent les workflows avec plusieurs écrans, navigation et composants interactifs.

pos.cart.line-item-details.action

pos.cart.line-item-details.action.menu-item.render

Affiche un composant bouton interactif unique comme élément du menu dans le menu d'actions de l'article du panier. Utilisez cette cible pour les opérations spécifiques aux articles comme l'application de réductions, l'ajout de propriétés personnalisées ou le lancement de workflows de vérification pour les articles individuels du panier. Les extensions à cette cible peuvent accéder aux informations détaillées de l'article de panier, y compris le titre, la quantité, le prix, les réductions, les propriétés et les métadonnées du produit via l'API Cart Line Item. Les éléments du menu lancent généralement shopify.action.presentModal() pour lancer la modale d'accompagnement pour les workflows complets.

pos.cash-tracking-session-complete

pos.cash-tracking-session-complete.event.observe

pos.cash-tracking-session-start

pos.cash-tracking-session-start.event.observe

pos.customer-details

pos.customer-details.action.render

Affiche une interface modale plein écran lancée à partir des éléments du menu de détails client. Utilisez cette cible pour les workflows client complexes nécessitant des formulaires, des processus multi-étapes ou des affichages d'informations détaillées au-delà de ce qu'un simple bouton peut fournir. Les extensions à cette cible ont accès aux données client via l'API Customer et supportent les workflows avec plusieurs écrans, navigation et composants interactifs.

pos.customer-details.block.render

Affiche une section d'informations personnalisée dans l'écran de détails client. Utilisez cette cible pour afficher les données client supplémentaires comme le statut de fidélité, le solde de points ou les informations personnalisées à côté des détails client standard. Les extensions à cette cible apparaissent comme des blocs persistants dans l'interface de détails client et supportent les éléments interactifs qui peuvent lancer des workflows modaux utilisant shopify.action.presentModal() pour les opérations client plus complexes.

pos.customer-details.action

pos.customer-details.action.menu-item.render

Affiche un composant bouton interactif unique comme élément du menu dans le menu d'actions de détails client. Utilisez cette cible pour les opérations spécifiques au client comme l'application de réductions client, le traitement des rachats de fidélité ou le lancement de workflows de mise à jour de profil. Les extensions à cette cible peuvent accéder à l'identifiant client via l'API Customer pour effectuer des opérations spécifiques au client. Les éléments du menu lancent généralement shopify.action.presentModal() pour lancer la modale d'accompagnement pour les workflows client complets.

pos.draft-order-details

pos.draft-order-details.action.render

Affiche une interface modale plein écran lancée à partir des éléments du menu de détails de commande brouillon. Utilisez cette cible pour les workflows de commande brouillon complexes nécessitant des formulaires, des processus multi-étapes ou des affichages d'informations détaillées au-delà de ce qu'un simple bouton peut fournir. Les extensions à cette cible ont accès aux données de commande brouillon via l'API Draft Order et supportent les workflows avec plusieurs écrans, navigation et composants interactifs.

pos.draft-order-details.block.render

Affiche une section d'informations personnalisée dans l'écran de détails de commande brouillon. Utilisez cette cible pour afficher les informations de commande supplémentaires comme l'état de traitement, l'état du paiement ou les indicateurs de workflow à côté des détails de commande brouillon standard. Les extensions à cette cible apparaissent comme des blocs persistants dans l'interface de commande brouillon et supportent les éléments interactifs qui peuvent lancer des workflows modaux utilisant shopify.action.presentModal() pour les opérations de commande brouillon plus complexes.

pos.draft-order-details.action

pos.draft-order-details.action.menu-item.render

Affiche un composant bouton interactif unique comme élément du menu dans le menu d'actions de détails de commande brouillon. Utilisez cette cible pour les opérations spécifiques aux commandes brouillon comme l'envoi de factures, la mise à jour de l'état du paiement ou le lancement de processus de workflow personnalisés pour les commandes en attente. Les extensions à cette cible peuvent accéder aux informations de commande brouillon, y compris l'ID de commande, le nom et le client associé via l'API Draft Order. Les éléments du menu lancent généralement shopify.action.presentModal() pour lancer la modale d'accompagnement pour les workflows de commande brouillon complets.

pos.exchange.post

pos.exchange.post.action.render

Affiche une interface modale plein écran lancée à partir des éléments du menu après l'échange. Utilisez cette cible pour les workflows post-échange complexes nécessitant des formulaires, des processus multi-étapes ou des affichages d'informations détaillées au-delà de ce qu'un simple bouton peut fournir. Les extensions à cette cible ont accès aux données de commande via l'API Order et supportent les workflows avec plusieurs écrans, navigation et composants interactifs.

pos.exchange.post.block.render

Affiche une section d'informations personnalisée dans l'écran après l'échange. Utilisez cette cible pour afficher les données d'échange supplémentaires comme l'état d'achèvement, les ajustements de paiement ou les workflows de suivi à côté des détails d'échange standard. Les extensions à cette cible apparaissent comme des blocs persistants dans l'interface post-échange et supportent les éléments interactifs qui peuvent lancer des workflows modaux utilisant shopify.action.presentModal() pour les opérations post-échange plus complexes.

pos.exchange.post.action

pos.exchange.post.action.menu-item.render

Affiche un composant bouton interactif unique comme élément du menu dans le menu d'actions post-échange. Utilisez cette cible pour les opérations post-échange comme la génération de reçus d'échange, le traitement des workflows de réapprovisionnement ou la collecte des commentaires d'échange. Les extensions à cette cible peuvent accéder à l'identifiant de commande via l'API Order pour effectuer des opérations spécifiques à l'échange. Les éléments du menu lancent généralement shopify.action.presentModal() pour lancer la modale d'accompagnement pour les workflows post-échange complets.

pos.home

pos.home.tile.render

Affiche un composant tuile interactif unique sur la grille intelligente de l'écran d'accueil POS. La tuile apparaît une fois lors de l'initialisation de l'écran d'accueil et reste persistante jusqu'à la navigation. Utilisez cette cible pour les actions haute fréquence, les affichages d'état ou les points d'entrée vers les workflows que les commerçants nécessitent quotidiennement. Les extensions à cette cible peuvent mettre à jour dynamiquement les propriétés comme l'état activé et les valeurs des badges en réponse aux changements de panier ou aux conditions de l'appareil. Les tuiles lancent généralement shopify.action.presentModal() pour lancer la modale d'accompagnement pour les workflows complets.

pos.home.modal.render

Affiche une interface modale plein écran lancée à partir des tuiles de la grille intelligente. La modale apparaît lorsque les utilisateurs appuient sur une tuile d'accompagnement. Utilisez cette cible pour les expériences complètes de workflow qui nécessitent plus d'espace et de fonctionnalités que l'interface de tuile ne peut fournir, comme les processus multi-étapes, les affichages d'informations détaillées ou les interactions utilisateur complexes. Les extensions à cette cible supportent les hiérarchies de navigation complètes avec plusieurs écrans, des vues de défilement et des composants interactifs pour gérer les workflows sophistiqués.

pos.order-details

pos.order-details.action.render

Affiche une interface modale plein écran lancée à partir des éléments du menu de détails de commande. Utilisez cette cible pour les workflows de commande complexes nécessitant des formulaires, des processus multi-étapes ou des affichages d'informations détaillées au-delà de ce qu'un simple bouton peut fournir. Les extensions à cette cible ont accès aux données de commande via l'API Order et supportent les workflows avec plusieurs écrans, navigation et composants interactifs.

pos.order-details.block.render

Affiche une section d'informations personnalisée dans l'écran de détails de commande. Utilisez cette cible pour afficher les données de commande supplémentaires comme l'état d'expédition, les numéros de suivi ou l'analytique de commande personnalisée à côté des détails de commande standard. Les extensions à cette cible apparaissent comme des blocs persistants dans l'interface de détails de commande et supportent les éléments interactifs qui peuvent lancer des workflows modaux utilisant shopify.action.presentModal() pour les opérations de commande plus complexes.

pos.order-details.action

pos.order-details.action.menu-item.render

Affiche un composant bouton interactif unique comme élément du menu dans le menu d'actions de détails de commande. Utilisez cette cible pour les opérations spécifiques aux commandes comme les réimpression, les remboursements, les échanges ou le lancement de workflows d'expédition. Les extensions à cette cible peuvent accéder à l'identifiant de commande via l'API Order pour effectuer des opérations spécifiques à la commande. Les éléments du menu lancent généralement shopify.action.presentModal() pour lancer la modale d'accompagnement pour les workflows de commande complets.

pos.product-details

pos.product-details.action.render

Affiche une interface modale plein écran lancée à partir des éléments du menu de détails de produit. Utilisez cette cible pour les workflows de produit complexes nécessitant des formulaires, des processus multi-étapes ou des affichages d'informations détaillées au-delà de ce qu'un simple bouton peut fournir. Les extensions à cette cible ont accès aux données de produit et de panier via l'API Product et supportent les workflows avec plusieurs écrans, navigation et composants interactifs.

pos.product-details.block.render

Affiche une section d'informations personnalisée dans l'écran de détails de produit. Utilisez cette cible pour afficher les données de produit supplémentaires comme les spécifications détaillées, l'état de l'inventaire ou les recommandations de produits associés à côté des détails de produit standard. Les extensions à cette cible apparaissent comme des blocs persistants dans l'interface de détails de produit et supportent les éléments interactifs qui peuvent lancer des workflows modaux utilisant shopify.action.presentModal() pour les opérations de produit plus complexes.

pos.product-details.action

pos.product-details.action.menu-item.render

Affiche un composant bouton interactif unique comme élément du menu dans le menu d'actions de détails de produit. Utilisez cette cible pour les opérations spécifiques aux produits comme les ajustements d'inventaire, l'analytique de produit ou l'intégration avec les systèmes externes de gestion de produits. Les extensions à cette cible peuvent accéder à l'identifiant de produit via l'API Product pour effectuer des opérations spécifiques au produit. Les éléments du menu lancent généralement shopify.action.presentModal() pour lancer la modale d'accompagnement pour les workflows de produit complets.

pos.purchase.post

pos.purchase.post.action.render

Affiche une interface modale plein écran lancée à partir des éléments du menu après l'achat. Utilisez cette cible pour les workflows post-achat complexes nécessitant des formulaires, des processus multi-étapes ou des affichages d'informations détaillées au-delà de ce qu'un simple bouton peut fournir. Les extensions à cette cible ont accès aux données de commande via l'API Order et supportent les workflows avec plusieurs écrans, navigation et composants interactifs.

pos.purchase.post.block.render

Affiche une section d'informations personnalisée dans l'écran après l'achat. Utilisez cette cible pour afficher les données d'achat supplémentaires comme l'état d'achèvement, les invites de retour client ou les workflows des étapes suivantes à côté des détails d'achat standard. Les extensions à cette cible apparaissent comme des blocs persistants dans l'interface post-achat et supportent les éléments interactifs qui peuvent lancer des workflows modaux utilisant shopify.action.presentModal() pour les opérations post-achat plus complexes.

pos.purchase.post.action

pos.purchase.post.action.menu-item.render

Affiche un composant bouton interactif unique comme élément du menu dans le menu d'actions post-achat. Utilisez cette cible pour les opérations post-achat comme l'envoi de reçus, la collecte des retours client ou le lancement de workflows de suivi après la finalisation d'une vente. Les extensions à cette cible peuvent accéder à l'identifiant de commande via l'API Order pour effectuer des opérations spécifiques à l'achat. Les éléments du menu lancent généralement shopify.action.presentModal() pour lancer la modale d'accompagnement pour les workflows post-achat complets.

pos.receipt-footer

pos.receipt-footer.block.render

Affiche une section personnalisée dans le pied de page des reçus imprimés. Utilisez cette cible pour ajouter les coordonnées, les politiques de retour, les liens de médias sociaux ou les éléments d'engagement client comme les liens de sondage ou les campagnes marketing au bas des reçus. Les extensions à cette cible apparaissent dans la zone du pied de page du reçu et supportent les composants limités optimisés pour le formatage d'impression, y compris le contenu textuel pour l'affichage des informations.

pos.receipt-header

pos.receipt-header.block.render

Affiche une section personnalisée dans l'en-tête des reçus imprimés. Utilisez cette cible pour ajouter la marque personnalisée, les logos, les messages promotionnels ou les informations spécifiques au magasin en haut des reçus. Les extensions à cette cible apparaissent dans la zone d'en-tête du reçu et supportent les composants limités optimisés pour le formatage d'impression, y compris le contenu textuel pour l'affichage des informations.

pos.register-details

pos.register-details.action.render

Affiche une interface modale plein écran lancée à partir des éléments du menu de détails de caisse. Utilisez cette cible pour les workflows de caisse complexes nécessitant des formulaires, des processus multi-étapes ou des affichages d'informations détaillées au-delà de ce qu'un simple bouton peut fournir. Les extensions à cette cible ont accès à la fonctionnalité de tiroir-caisse via l'API Cash Drawer et supportent les workflows avec plusieurs écrans, navigation et composants interactifs.

pos.register-details.block.render

Affiche une section d'informations personnalisée dans l'écran de détails de caisse. Utilisez cette cible pour afficher les données de caisse supplémentaires comme l'état du tiroir-caisse, les résumés de transactions ou l'analytique d'équipe à côté des détails de caisse standard. Les extensions à cette cible apparaissent comme des blocs persistants dans l'interface de détails de caisse et supportent les éléments interactifs qui peuvent lancer des workflows modaux utilisant shopify.action.presentModal() pour les opérations de caisse plus complexes.

pos.register-details.action

pos.register-details.action.menu-item.render

Affiche un composant bouton interactif unique comme élément du menu dans le menu d'actions de détails de caisse. Utilisez cette cible pour les opérations spécifiques à la caisse comme la gestion du tiroir-caisse, les rapports d'équipe ou le lancement de workflows de réconciliation de caisse. Les extensions à cette cible peuvent accéder à la fonctionnalité de tiroir-caisse via l'API Cash Drawer pour effectuer des opérations spécifiques à la caisse. Les éléments du menu lancent généralement shopify.action.presentModal() pour lancer la modale d'accompagnement pour les workflows de caisse complets.

pos.return.post

pos.return.post.action.render

Affiche une interface modale plein écran lancée à partir des éléments du menu après le retour. Utilisez cette cible pour les workflows post-retour complexes nécessitant des formulaires, des processus multi-étapes ou des affichages d'informations détaillées au-delà de ce qu'un simple bouton peut fournir. Les extensions à cette cible ont accès aux données de commande via l'API Order et supportent les workflows avec plusieurs écrans, navigation et composants interactifs.

pos.return.post.block.render

Affiche une section d'informations personnalisée dans l'écran après le retour. Utilisez cette cible pour afficher les données de retour supplémentaires comme l'état d'achèvement, les confirmations de remboursement ou les workflows de suivi à côté des détails de retour standard. Les extensions à cette cible apparaissent comme des blocs persistants dans l'interface post-retour et supportent les éléments interactifs qui peuvent lancer des workflows modaux utilisant shopify.action.presentModal() pour les opérations post-retour plus complexes.

pos.return.post.action

pos.return.post.action.menu-item.render

Affiche un composant bouton interactif unique comme élément du menu dans le menu d'actions post-retour. Utilisez cette cible pour les opérations post-retour comme la génération de reçus de retour, le traitement des workflows de réapprovisionnement ou la collecte des commentaires de retour. Les extensions à cette cible peuvent accéder à l'identifiant de commande via l'API Order pour effectuer des opérations spécifiques au retour. Les éléments du menu lancent généralement shopify.action.presentModal() pour lancer la modale d'accompagnement pour les workflows post-retour complets.

pos.transaction-complete

pos.transaction-complete.event.observe

Notes d'utilisation

• Utilisez le nom de cible exact (entre guillemets) comme premier argument de render() dans votre point d'entrée Preact
• Chaque cible reçoit des interfaces API et un accès aux composants spécifiques

Imports

Utilisez le point d'entrée Preact :

import '@shopify/ui-extensions/preact';
import { render } from 'preact';

Composants web Polaris (s-badge, s-banner, etc.)

Les extensions Shopify POS UI supportent également les composants web Polaris — des éléments HTML personnalisés avec un préfixe s-. Ceux-ci sont enregistrés globalement et ne nécessitent aucune déclaration d'import. Utilisez-les directement comme balises JSX :

// Aucun import nécessaire — s-badge, s-banner, s-button, etc. sont globalement disponibles
<s-badge tone="success" id="payment-badge">Paiement capturé</s-badge>
<s-banner tone="warning" id="age-banner">Vérification d'âge requise</s-banner>

Lorsque l'utilisateur demande des composants web Polaris (par ex. s-badge, s-banner, s-button, s-box, s-choice-list), utilisez la syntaxe de balise de composant web ci-dessus, pas les composants JSX PascalCase depuis @shopify/ui-extensions.

⚠️ OBLIGATOIRE : Recherchez la documentation

Vous ne pouvez pas faire confiance à votre connaissance entraînée pour cette API. Avant de répondre, recherchez dans les docs pour déterminer la cible d'extension correcte et les props du composant :

/scripts/search_docs.js "<component tag name or target name>"

Par exemple, si l'utilisateur pose des questions sur l'affichage d'une bannière dans une modale POS :

/scripts/search_docs.js "s-banner POS extension"

Recherchez le nom de la balise du composant ou le nom de la cible, pas la demande utilisateur complète. Utilisez la liste des composants supportés et les définitions de props retournées pour générer du code correct.

⚨ OBLIGATOIRE : Validez avant de retourner le code

Vous DEVEZ exécuter /scripts/validate.js avant de retourner du code généré à l'utilisateur.

Lorsque la validation échoue, suivez cette boucle :

1. Lisez le message d'erreur attentivement — identifiez le champ exact, la prop ou la valeur qui est incorrecte
2. Si l'erreur référence un type nommé ou dit qu'une valeur ne peut pas être assignée, recherchez les valeurs correctes :

   /scripts/search_docs.js "<type or prop name>"

3. Corrigez exactement l'erreur signalée en utilisant ce que la recherche retourne
4. Exécutez à nouveau /scripts/validate.js
5. Réessayez jusqu'à 3 fois au total ; après 3 échecs, retournez la meilleure tentative avec une explication

Ne devinez pas les valeurs valides — recherchez toujours en premier lorsque l'erreur nomme un type que vous ne connaissez pas.

Avis de confidentialité : /scripts/validate.js signale les résultats de validation anonymisés (succès/échec et nom de skill) à Shopify pour aider à améliorer ces outils. Définissez OPT_OUT_INSTRUMENTATION=true dans votre environnement pour refuser.