<!-- AUTO-GENERATED — do not edit directly. Edit src/data/raw-api-instructions/{api}.md in shopify-dev-tools, then run: npm run generate_agent_skills (outputs to distributed-agent-skills/) -->

name: shopify-pos-ui description: "Créer des applications de point de vente au détail à l'aide des composants d'interface utilisateur Shopify POS. Ces composants fournissent une interface cohérente et familière pour les applications de PDV. Les extensions d'interface utilisateur POS prennent également en charge la génération de nouvelles extensions de PDV à l'aide des commandes Shopify CLI. Keywords: 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 framework d'interface utilisateur Shopify pos-ui.

Vous devriez 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 en extensions d'interface utilisateur Shopify POS générant du code Preact prêt pour la production, type-safe, qui étend les fonctionnalités du PDV tout en respectant les normes de performance, sécurité et expérience utilisateur. Tous les exemples de code dans ce document sont à titre informatif uniquement. VÉRIFIEZ TOUJOURS la documentation API réelle avant d'utiliser toute méthode, composant ou propriété.

🚨 OBLIGATOIRE : TOUJOURS UTILISER LE CLI POUR GÉNÉRER UNE NOUVELLE EXTENSION ET NE JAMAIS CRÉER MANUELLEMENT LA STRUCTURE DE L'APPLICATION OU LES FICHIERS DE CONFIGURATION. TOUJOURS utiliser CLI pour générer les nouvelles extensions. NE JAMAIS créer 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, affichez la commande exacte et demandez à l'utilisateur de l'exécuter localement.

Flux de création d'extension d'interface utilisateur POS

<pos-extension-todo-flow> <step id="1"> Déterminer si Shopify CLI est installé <step id="1.1">Si non installé : Installer @shopify/cli@latest à l'aide du gestionnaire de paquets</step> <step id="1.2">Si installé : Exécuter shopify --version pour vérifier que CLI est supérieur à 3.85.3. Si ce n'est pas le cas, effectuer une mise à niveau vers @shopify/cli@latest à l'aide du gestionnaire de paquets</step> </step> <step id="2"> Déterminer 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 pas d'application existante : <step id="2.2.1">Exécuter 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">Ignorer toutes les extensions existantes dans l'application. Générer uniquement la nouvelle extension. NE PAS modifier les extensions existantes.</step> <step id="2.3.2">Exécuter 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 PAS l'utiliser. Exécuter la commande telle quelle.</step> </step> </step> </pos-extension-todo-flow> </system-instructions>

Si aucune cible d'extension n'est spécifiée, consultez la documentation pour déterminer la cible appropriée à votre cas d'usage avant de générer le code.

Cibles d'extension disponibles pour pos-ui

Surface : point-of-sale Nombre total de 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 de menu des détails de ligne de panier. Utilisez cette cible pour les flux de travail de ligne d'article complexes qui nécessitent 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 via l'API Cart Line Item et prennent en charge les flux de travail 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 de bouton interactif unique en tant qu'élément de menu dans le menu d'action de ligne de panier. Utilisez cette cible pour les opérations spécifiques aux articles comme l'application de remises, l'ajout de propriétés personnalisées ou le lancement de flux de vérification pour des articles de panier individuels. Les extensions à cette cible peuvent accéder aux informations détaillées de ligne d'article incluant le titre, la quantité, le prix, les remises, les propriétés et les métadonnées de produit via l'API Cart Line Item. Les éléments de menu invoquent généralement shopify.action.presentModal() pour lancer la modale compagnon pour des flux de travail 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 de menu des détails client. Utilisez cette cible pour les flux de travail client complexes qui nécessitent 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 prennent en charge les flux de travail avec plusieurs écrans, navigation et composants interactifs.

pos.customer-details.block.render

Affiche une section d'informations personnalisée au sein de l'écran des 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 aux côtés des détails standard du client. Les extensions à cette cible apparaissent comme des blocs persistants au sein de l'interface des détails client et prennent en charge les éléments interactifs qui peuvent lancer des flux de travail modaux à l'aide de shopify.action.presentModal() pour les opérations client plus complexes.

pos.customer-details.action

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

Affiche un composant de bouton interactif unique en tant qu'élément de menu dans le menu d'action des détails client. Utilisez cette cible pour les opérations spécifiques au client comme l'application de remises client, le traitement des remboursements de fidélité ou le lancement de flux 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 de menu invoquent généralement shopify.action.presentModal() pour lancer la modale compagnon pour des flux de travail client complets.

pos.draft-order-details

pos.draft-order-details.action.render

Affiche une interface modale plein écran lancée à partir des éléments de menu des détails de commande préliminaire. Utilisez cette cible pour les flux de travail de commande préliminaire complexes qui nécessitent 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 préliminaire via l'API Draft Order et prennent en charge les flux de travail avec plusieurs écrans, navigation et composants interactifs.

pos.draft-order-details.block.render

Affiche une section d'informations personnalisée au sein de l'écran des détails de commande préliminaire. Utilisez cette cible pour afficher les informations de commande supplémentaires comme l'état du traitement, l'état du paiement ou les indicateurs de flux de travail aux côtés des détails standard de commande préliminaire. Les extensions à cette cible apparaissent comme des blocs persistants au sein de l'interface de commande préliminaire et prennent en charge les éléments interactifs qui peuvent lancer des flux de travail modaux à l'aide de shopify.action.presentModal() pour les opérations de commande préliminaire plus complexes.

pos.draft-order-details.action

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

Affiche un composant de bouton interactif unique en tant qu'élément de menu dans le menu d'action des détails de commande préliminaire. Utilisez cette cible pour les opérations spécifiques à la commande préliminaire comme l'envoi de factures, la mise à jour du statut de paiement ou le lancement de processus de flux de travail personnalisés pour les commandes en attente. Les extensions à cette cible peuvent accéder aux informations de commande préliminaire incluant l'ID de commande, le nom et le client associé via l'API Draft Order. Les éléments de menu invoquent généralement shopify.action.presentModal() pour lancer la modale compagnon pour des flux de travail de commande préliminaire complets.

pos.exchange.post

pos.exchange.post.action.render

Affiche une interface modale plein écran lancée à partir des éléments de menu post-échange. Utilisez cette cible pour les flux de travail post-échange complexes qui nécessitent 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 prennent en charge les flux de travail avec plusieurs écrans, navigation et composants interactifs.

pos.exchange.post.block.render

Affiche une section d'informations personnalisée au sein de l'écran post-é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 flux de travail de suivi aux côtés des détails d'échange standard. Les extensions à cette cible apparaissent comme des blocs persistants au sein de l'interface post-échange et prennent en charge les éléments interactifs qui peuvent lancer des flux de travail modaux à l'aide de 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 de bouton interactif unique en tant qu'élément de menu dans le menu d'action post-échange. Utilisez cette cible pour les opérations post-échange comme la génération de reçus d'échange, le traitement des flux de travail de restockage ou la collecte de commentaires sur l'é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 de menu invoquent généralement shopify.action.presentModal() pour lancer la modale compagnon pour des flux de travail post-échange complets.

pos.home

pos.home.tile.render

Affiche un composant de tuile interactif unique sur la grille intelligente de l'écran d'accueil du PDV. La tuile s'affiche une fois lors de l'initialisation de l'écran d'accueil et reste persistante jusqu'à ce qu'une navigation se produise. Utilisez cette cible pour les actions haute fréquence, les affichages d'état ou les points d'entrée aux flux de travail dont les commerçants ont besoin quotidiennement. Les extensions à cette cible peuvent mettre à jour dynamiquement les propriétés comme l'état activé et les valeurs de badge en réponse aux modifications du panier ou aux conditions de l'appareil. Les tuiles invoquent généralement shopify.action.presentModal() pour lancer la modale compagnon pour des flux de travail complets.

pos.home.modal.render

Affiche une interface modale plein écran lancée à partir des tuiles de grille intelligente compagnon. La modale s'affiche lorsque les utilisateurs appuient sur une tuile compagnon. Utilisez cette cible pour les expériences de flux de travail complets 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 prennent en charge les hiérarchies de navigation complètes avec plusieurs écrans, vues de défilement et composants interactifs pour gérer les flux de travail sophistiqués.

pos.order-details

pos.order-details.action.render

Affiche une interface modale plein écran lancée à partir des éléments de menu des détails de commande. Utilisez cette cible pour les flux de travail de commande complexes qui nécessitent 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 prennent en charge les flux de travail avec plusieurs écrans, navigation et composants interactifs.

pos.order-details.block.render

Affiche une section d'informations personnalisée au sein de l'écran des détails de commande. Utilisez cette cible pour afficher les données de commande supplémentaires comme l'état d'exécution, les numéros de suivi ou les analyses de commande personnalisées aux côtés des détails standard de commande. Les extensions à cette cible apparaissent comme des blocs persistants au sein de l'interface des détails de commande et prennent en charge les éléments interactifs qui peuvent lancer des flux de travail modaux à l'aide de 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 de bouton interactif unique en tant qu'élément de menu dans le menu d'action des détails de commande. Utilisez cette cible pour les opérations spécifiques à la commande comme les réimpressions, les remboursements, les échanges ou le lancement de flux de travail d'exécution. 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 de menu invoquent généralement shopify.action.presentModal() pour lancer la modale compagnon pour des flux de travail de commande complets.

pos.product-details

pos.product-details.action.render

Affiche une interface modale plein écran lancée à partir des éléments de menu des détails de produit. Utilisez cette cible pour les flux de travail de produit complexes qui nécessitent 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 prennent en charge les flux de travail avec plusieurs écrans, navigation et composants interactifs.

pos.product-details.block.render

Affiche une section d'informations personnalisée au sein de l'écran des 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 des stocks ou les recommandations de produits associés aux côtés des détails standard de produit. Les extensions à cette cible apparaissent comme des blocs persistants au sein de l'interface des détails de produit et prennent en charge les éléments interactifs qui peuvent lancer des flux de travail modaux à l'aide de 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 de bouton interactif unique en tant qu'élément de menu dans le menu d'action des détails de produit. Utilisez cette cible pour les opérations spécifiques au produit comme les ajustements d'inventaire, l'analyse des produits ou l'intégration avec les systèmes de gestion de produits externes. 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 de menu invoquent généralement shopify.action.presentModal() pour lancer la modale compagnon pour des flux de travail de produit complets.

pos.purchase.post

pos.purchase.post.action.render

Affiche une interface modale plein écran lancée à partir des éléments de menu post-achat. Utilisez cette cible pour les flux de travail post-achat complexes qui nécessitent 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 prennent en charge les flux de travail avec plusieurs écrans, navigation et composants interactifs.

pos.purchase.post.block.render

Affiche une section d'informations personnalisée au sein de l'écran post-achat. Utilisez cette cible pour afficher les données d'achat supplémentaires comme l'état d'achèvement, les invites de commentaires client ou les flux de travail de prochaines étapes aux côtés des détails standard d'achat. Les extensions à cette cible apparaissent comme des blocs persistants au sein de l'interface post-achat et prennent en charge les éléments interactifs qui peuvent lancer des flux de travail modaux à l'aide de 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 de bouton interactif unique en tant qu'élément de menu dans le menu d'action post-achat. Utilisez cette cible pour les opérations post-achat comme l'envoi de reçus, la collecte de commentaires clients ou le lancement de flux de travail de suivi après la réalisation 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 de menu invoquent généralement shopify.action.presentModal() pour lancer la modale compagnon pour des flux de travail post-achat complets.

pos.receipt-footer

pos.receipt-footer.block.render

Affiche une section personnalisée au 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 d'enquête ou les campagnes marketing au bas des reçus. Les extensions à cette cible apparaissent dans la zone de pied de page du reçu et prennent en charge les composants limités optimisés pour le formatage d'impression, incluant le contenu texte pour l'affichage d'informations.

pos.receipt-header

pos.receipt-header.block.render

Affiche une section personnalisée en en-tête des reçus imprimés. Utilisez cette cible pour ajouter l'image de 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 prennent en charge les composants limités optimisés pour le formatage d'impression, incluant le contenu texte pour l'affichage d'informations.

pos.register-details

pos.register-details.action.render

Affiche une interface modale plein écran lancée à partir des éléments de menu des détails de registre. Utilisez cette cible pour les flux de travail de registre complexes qui nécessitent 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é du tiroir-caisse via l'API Cash Drawer et prennent en charge les flux de travail avec plusieurs écrans, navigation et composants interactifs.

pos.register-details.block.render

Affiche une section d'informations personnalisée au sein de l'écran des détails de registre. Utilisez cette cible pour afficher les données de registre supplémentaires comme l'état du tiroir-caisse, les résumés de transactions ou l'analyse des quarts de travail aux côtés des détails standard de registre. Les extensions à cette cible apparaissent comme des blocs persistants au sein de l'interface des détails de registre et prennent en charge les éléments interactifs qui peuvent lancer des flux de travail modaux à l'aide de shopify.action.presentModal() pour les opérations de registre plus complexes.

pos.register-details.action

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

Affiche un composant de bouton interactif unique en tant qu'élément de menu dans le menu d'action des détails de registre. Utilisez cette cible pour les opérations spécifiques au registre comme la gestion du tiroir-caisse, les rapports de quart de travail ou le lancement de flux de travail de rapprochement de caisse. Les extensions à cette cible peuvent accéder à la fonctionnalité du tiroir-caisse via l'API Cash Drawer pour effectuer des opérations spécifiques au registre. Les éléments de menu invoquent généralement shopify.action.presentModal() pour lancer la modale compagnon pour des flux de travail de registre complets.

pos.return.post

pos.return.post.action.render

Affiche une interface modale plein écran lancée à partir des éléments de menu post-retour. Utilisez cette cible pour les flux de travail post-retour complexes qui nécessitent 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 prennent en charge les flux de travail avec plusieurs écrans, navigation et composants interactifs.

pos.return.post.block.render

Affiche une section d'informations personnalisée au sein de l'écran post-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 flux de travail de suivi aux côtés des détails standard de retour. Les extensions à cette cible apparaissent comme des blocs persistants au sein de l'interface post-retour et prennent en charge les éléments interactifs qui peuvent lancer des flux de travail modaux à l'aide de 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 de bouton interactif unique en tant qu'élément de menu dans le menu d'action post-retour. Utilisez cette cible pour les opérations post-retour comme la génération de reçus de retour, le traitement des flux de travail de restockage ou la collecte de commentaires sur le 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 de menu invoquent généralement shopify.action.presentModal() pour lancer la modale compagnon pour des flux de travail post-retour complets.

pos.transaction-complete

pos.transaction-complete.event.observe

Notes d'utilisation

• Utilisez le nom de cible exact (entre guillemets) lors de l'enregistrement de votre extension avec shopify.extend()
• Chaque cible reçoit des interfaces API spécifiques et un accès aux composants

Importations

Toujours importer à partir de @shopify/ui-extensions/point-of-sale — jamais à partir de @shopify/pos-ui-extensions, @shopify/polaris-web-components, @shopify/polaris-web-components/pos, ou tout autre paquet. Ces paquets n'existent pas.

import { reactExtension, Badge, Banner, Button, Screen, ScrollView, Text } from '@shopify/ui-extensions/point-of-sale';

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

Les extensions d'interface utilisateur POS prennent également en charge 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 instruction d'importation. Utilisez-les directement en tant que balises JSX :

// Aucune importation nécessaire — s-badge, s-banner, s-button, etc. sont globalement disponibles
<s-badge tone="success" id="payment-badge">Payment captured</s-badge>
<s-banner tone="warning" id="age-banner">Age verification required</s-banner>

Quand l'utilisateur demande des composants web Polaris (par exemple 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 à partir de @shopify/ui-extensions.

⚠️ OBLIGATOIRE : Rechercher dans la documentation

Vous ne pouvez pas faire confiance à votre connaissance entraînée pour cette API. Avant de répondre, consultez la documentation pour déterminer la cible d'extension correcte et les props des composants :

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

Par exemple, si l'utilisateur demande l'affichage d'une bannière dans une modale POS :

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

Recherchez le nom de balise du composant ou le nom de cible, pas l'invite utilisateur complète. Utilisez la liste des composants pris en charge retournée et les définitions de props pour générer du code correct.

⚠️ OBLIGATOIRE : Valider avant de retourner le code

NE PAS retourner le code à l'utilisateur jusqu'à ce que /scripts/validate.js se termine avec le code 0. NE PAS demander à l'utilisateur de l'exécuter.

Exemple :

validate_component_codeblocks
- code: `
  import { render } from 'preact';

  export default function Extension() {
    return (
      <s-page heading="Age verification">
        <s-scroll-box>
          <s-banner heading="Verification required" tone="warning">
            Confirm the customer meets the legal age requirement before completing this sale.
            <s-button slot="primary-action">Customer verified</s-button>
          </s-banner>
        </s-scroll-box>
      </s-page>
    );
  }
  `
- target: "pos.home.modal.render"

Si la validation échoue avec une propriété inconnue ou une erreur de type, recherchez les valeurs correctes avant de réessayer :

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

⚠️ OBLIGATOIRE : Valider avant de retourner le code

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

Quand la validation échoue, suivez cette boucle :

1. Lisez attentivement le message d'erreur — identifiez le champ, la propriété ou la valeur exacte qui est incorrect
2. Si l'erreur référence un type nommé ou indique qu'une valeur n'est pas assignable, 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 /scripts/validate.js à nouveau
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 — cherchez toujours d'abord quand l'erreur nomme un type que vous ne connaissez pas.

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