# Cas d'usage des métadonnées Utilisez ces exemples pour enregistrer vos données sur des objets Stripe. Utilisez [metadata](https://docs.stripe.com/api/metadata.md) pour enregistrer vos données importantes sur les objets Stripe à l’aide de ces exemples courants. Les cas d’usage suivants ne sont pas exhaustifs ; la façon dont vous utilisez les métadonnées dépend de vos cas d’usage spécifiques. > N’incluez pas d’informations sensibles dans `metadata`, telles que des données personnelles, des coordonnées bancaires ou des informations de cartes personnelles. ## Enregistrer les ID des objets ou des enregistrements Vous pouvez utiliser les métadonnées dans les objets Stripe pour enregistrer les ID qui appartiennent aux objets ou aux enregistrements de vos autres systèmes. Cela vous permet d’établir des références entre les objets Stripe et les ressources connexes de vos autres systèmes. ### ID de commande ou de panier Lorsque vous créez des ID pour suivre les paniers de vos clients, vous pouvez les enregistrer en tant que métadonnées sur les [sessions Checkout](https://docs.stripe.com/api/checkout/sessions.md). Cela vous permet d’utiliser l’objet Stripe associé pour localiser le panier associé dans votre système une fois le processus de paiement terminé. Enregistrez l’ID du panier dans les métadonnées de la session Checkout après l’avoir créé : ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ --data-urlencode "success_url=https://example.com/success" \ -d mode=payment \ -d "line_items[0][price]=price_1MotwRLkdIwHu7ixYcPLm5uZ" \ -d "line_items[0][quantity]=1" \ -d "metadata[cart_id]=cart_6943" ``` Vous pouvez ensuite consulter, mettre à jour ou supprimer l’ID de l’objet `Checkout Session`. Il apparaît également dans les événements envoyés à votre endpoint webhook qui contiennent cette session Checkout (y compris l’événement `checkout.session.completed`). ```json { "id": "evt_1PYCL6CzbZon1zn9VivIehz7", "object": "event", "api_version": "2024-06-20", "created": 1719948368, "data": { "object": { "id": "cs_test_a1Znb7gdtlLEPzSi8qMIJzvsSPpIBMKFWovXx0h0O43WS411PpICgCqKjw", "object": "checkout.session", ..."metadata": { "cart_id": "cart_6943" }, ... } }, ... "type": "checkout.session.completed" } ``` ### ID du client ou du CMS Vous pouvez associer les [objets Customer](https://docs.stripe.com/api/customers.md) que vous créez dans Stripe aux enregistrements de votre système de gestion des clients (CMS) afin de faciliter le suivi et la gestion de vos clients. Enregistrez l’ID de l’enregistrement client de votre CMS dans les métadonnées de l’objet Customer que vous créez dans Stripe. ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d "name=Jenny Rosen" \ -d "metadata[cms_id]=cust_6573" ``` Stripe inclut cette information dans les événements envoyés à votre endpoint webhook qui contiennent cet objet Customer. Par exemple, lorsque vous recevez des événements `customer.updated`, vous pouvez utiliser l’ID enregistré afin d’identifier l’enregistrement que vous devez mettre à jour dans votre CMS. ```json { "id": "evt_1PajAGCzbZon1zn9FUsn7IoG", "object": "event", "api_version": "2024-06-20", "created": 1720551204, "data": { "object": { "id": "cus_QRcNyZh9aZHXnI", "object": "customer", ..."metadata": { "cms_id": "cust_6573" }, ... } }, ... "type": "customer.updated" } ``` ## Suivi du traitement des commandes Utilisez les métadonnées pour enregistrer des données qui facilitent vos processus de traitement des commandes ou permettent leur suivi. ### ID de tarif ou de produit au niveau d’un Payment Intent Lorsque vous créez directement des [intentions de paiement](https://docs.stripe.com/api/payment_intents.md), vous pouvez les associer à vos [produits](https://docs.stripe.com/api/products.md) ou à vos [prix](https://docs.stripe.com/api/prices.md) à l’aide de métadonnées. Cela vous permet d’enregistrer l’ID des objets associés sur l’intention de paiement, qui ne dispose pas de champ dédié pour les lier à un prix ou à un produit. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=2000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]=true" \ -d "metadata[price_id]=price_1MoBy5LkdIwHu7ixZhnattbh" \ -d "metadata[product_id]=prod_NWjs8kKbJWmuuc" ``` Vous pouvez localiser l’ID de l’objet associé dans les événements qui incluent ce Payment Intent, tels que les événements `payment_intent.succeeded`. Transmettez ensuite les métadonnées de l’événement à vos processus en aval (par exemple, le traitement des commandes ou la gestion des stocks). ```json { "id": "evt_3PajIyCzbZon1zn90b9Wvsqf", "object": "event", "api_version": "2024-06-20", "created": 1720551759, "data": { "object": { "id": "pi_3PajIyCzbZon1zn901xQeOdi", "object": "payment_intent", ..."metadata": { "price_id": "price_1MoBy5LkdIwHu7ixZhnattbh", "product_id": "prod_NWjs8kKbJWmuuc" } ... } }, ... "type": "payment_intent.succeeded" } ``` ### État et suivi du traitement Après avoir lancé votre flux de traitement des commandes, vous pouvez utiliser les métadonnées pour enregistrer l’état actuel du traitement sur l’objet Stripe associé. Cela vous permet de récupérer un objet de Stripe et de recevoir simultanément l’état du paiement et celui du traitement. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=2000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]=true" \ -d "metadata[fulfillment_status]=fulfillment_not_started" ``` Pour mettre à jour l’état actuel du traitement : ```curl curl https://api.stripe.com/v1/payment_intents/{{INTENT_ID}} \ -u "<>:" \ -d "metadata[fulfillment_status]=shipping_label_created" ``` ## Suivre les liens d’affiliation Dans [certains cas](https://docs.stripe.com/metadata.md#exceptions), Stripe copie `metadata` à partir de l’objet original vers un objet lié. Si vous avez des affiliés qui hébergent des [Payment Links](https://docs.stripe.com/api/payment_links.md) sur leur site et offrent des incitations pour les ventes provenant de ces liens, vous pouvez utiliser ce comportement dans votre suivi des affiliés. Lorsque vous créez des liens de paiement, vous pouvez renseigner `metadata` en vue de suivre votre affilié : ```curl curl https://api.stripe.com/v1/payment_links \ -u "<>:" \ -d "line_items[0][price]=price_1MotwRLkdIwHu7ixYcPLm5uZ" \ -d "line_items[0][quantity]=1" \ -d "metadata[affiliate]=afl_7920" ``` Chaque fois qu’un client effectue un achat à partir de ce lien, Stripe crée une [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md) qui hérite des métadonnées que vous avez fournies sur le lien de paiement. Vous pouvez surveiller les événements `checkout.session.completed` en vue de recevoir des notifications de Stripe lorsqu’un client effectue un achat. Vous pouvez alors extraire les détails de suivi de votre affilié à partir des métadonnées de la Checkout Session afin d’attribuer la vente avec précision. ```json { "id": "evt_1PajfeCzbZon1zn9S7pNlQkU", "object": "event", "api_version": "2024-06-20", "created": 1720553150, "data": { "object": { "id": "cs_test_a1zgRtgzjvamTgTnqMqIaqP6zehBIkaM03iYzxNjZiJ7FMDRRhibd5w3gL", "object": "checkout.session", ..."metadata": { "affiliate": "afl_7920" }, ... } }, ... "type": "checkout.session.completed" } ``` ## Notes du magasin Vous pouvez utiliser les métadonnées pour enregistrer des notes sur les objets. Par exemple, pour créer une note indiquant l’heure d’appel préférée d’un client, ajoutez des métadonnées à l’objet [Customer](https://docs.stripe.com/api/customers.md) : ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d "name=Jenny Rosen" \ --data-urlencode "metadata[call_window]=10:00 AM - 2:00 PM" ``` Pour enregistrer une note expliquant pourquoi une [Invoice](https://docs.stripe.com/api/invoices.md) a été annulée, vous pouvez utiliser `metadata` au niveau de l’objet `Invoice` : ```curl curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}} \ -u "<>:" \ --data-urlencode "metadata[void_reason]=Duplicate of Invoice #011" ``` ## Définir indirectement des métadonnées L’emplacement de vos métadonnées détermine les types d’événements qui contiennent les informations que vous indiquez. De même, si vous suivez certains types d’événements dans votre intégration, cela détermine l’endroit où vous placez vos métadonnées. Certains points de terminaison de création d’objets contiennent plusieurs champs pour vos métadonnées : un pour enregistrer les métadonnées directement sur l’objet créé, et d’autres pour les définir sur les objets créés en aval. En savoir plus sur les [champs de métadonnées indirects](https://docs.stripe.com/metadata.md#set-indirectly). L’exemple suivant crée une [session Checkout](https://docs.stripe.com/api/checkout/sessions.md) qui génère un abonnement lorsqu’elle est terminée. Il utilise le champ `metadata` de niveau supérieur et le champ `subscription_data.metadata` : ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ --data-urlencode "success_url=https://example.com/success" \ -d mode=subscription \ -d "line_items[0][price]=price_1MotwRLkdIwHu7ixYcPLm5uZ" \ -d "line_items[0][quantity]=1" \ -d "metadata[checkout_metadata]=Checkout Session metadata goes here" \ -d "subscription_data[metadata][subscription_metadata]=Subscription metadata goes here" ``` Vous pouvez définir des métadonnées sur l’objet que vous créez (dans ce cas, la session Checkout). Une fois que le client a terminé le processus de paiement, les métadonnées fournies précédemment dans `subscription_data.metadata` sont définies sur l’objet [Subscription](https://docs.stripe.com/api/subscriptions.md) qui vient d’être créé. Cela détermine les événements qui incluent les métadonnées. Par exemple, les événements qui comprennent une session Checkout, tels que `checkout.session.completed`, contiennent les valeurs fournies par le paramètre `metadata` de niveau supérieur. ```json { "id": "evt_1PakshCzbZon1zn9PlQwJYn0", "object": "event", "api_version": "2024-06-20", "created": 1720557803, "data": { "object": { "id": "cs_test_a1lsYmNYnEqQAxHT9knVy8v7u7m5ChjKtyB3M68ovMCjUQgCADsCkUviUU", "object": "checkout.session", ..."metadata": { "checkout_metadata": "Checkout Session metadata goes here" }, ... } }, ... "type": "checkout.session.completed" } ``` Les événements qui incluent un objet `Subscription`, tels que `customer.subscription.created`, contiennent les valeurs fournies par `subscription_data.metadata`. Cependant, comme cet événement comprend un objet Subscription, Stripe fournit les valeurs dans le champ `metadata` de niveau supérieur sur l’objet Subscription. ```json { "id": "evt_1PaksgCzbZon1zn9x9u3MTSC", "object": "event", "api_version": "2024-06-20", "created": 1720557800, "data": { "object": { "id": "sub_1PaksdCzbZon1zn9D6DQjr9L", "object": "subscription", ..."metadata": { "subscription_metadata": "Subscription metadata goes here" }, ... } }, ... "type": "customer.subscription.created" } ``` Vous pouvez accéder aux métadonnées que vous avez fournies dans `subscription_data.metadata` dans les événements [invoice](https://docs.stripe.com/api/invoices.md). En effet, les métadonnées de l’abonnement sont transférées dans `subscription_details.metadata` sur les objets `Invoice` créés par l’abonnement. ```json { "id": "evt_1PaksgCzbZon1zn9wD24BlvY", "object": "event", "api_version": "2024-06-20", "created": 1720557800, "data": { "object": { "id": "in_1PaksdCzbZon1zn9Z4bl0z7k", "object": "invoice", ..."subscription_details": { "metadata": { "subscription_metadata": "Subscription metadata goes here" } ... } } }, ... "type": "invoice.finalized" } ``` ## Enregistrer de grandes quantités de métadonnées Utilisez les champs de métadonnées dans Stripe pour enregistrer des données directement ou stocker une clé de recherche externe de façon à accéder à des données supplémentaires à partir de votre propre base de données. Cela limite les informations que vous devez récupérer. ### Enregistrer des données structurées Les métadonnées peuvent accepter n’importe quelle chaîne, y compris celles représentant des données structurées comme le format JSON, jusqu’à [500 caractères](https://docs.stripe.com/metadata.md#data). Vous pouvez les utiliser pour enregistrer davantage de données dans vos champs de métadonnées. Cela réduit le nombre de clés auxquelles vous devez accéder pour récupérer toutes vos informations. ```curl curl https://api.stripe.com/v1/accounts \ -u "<>:" \ --data-urlencode "metadata[account_details]={\"sourcing_details\":{\"found_from\":\"web_search\",\"referrer\":\"user_123\",\"joined\":\"2024-01-01\"},\"tier_information\":{\"tier\":\"silver\",\"total_sales\":35,\"next_tier_at\":50,\"next_tier\":\"gold\"}}" ``` ### Enregistrer des métadonnées en externe Pour associer à un objet des données dépassant les [500 caractères](https://docs.stripe.com/metadata.md#data) autorisés par les champs de métadonnées fournis, stockez les données excédentaires dans votre propre base de données. Vous pouvez ensuite utiliser les métadonnées pour enregistrer l’ID ou la clé de recherche permettant d’accéder à ces informations. Cette approche est similaire à l’enregistrement de l’ID de tout autre enregistrement dans votre système. ```curl curl https://api.stripe.com/v1/accounts \ -u "<>:" \ -d "metadata[account_details_lookup_key]=rec_a1b2c3" ``` ## Utiliser les métadonnées avec d’autres API et produits Stripe Vous pouvez utiliser les métadonnées avec d’autres API et produits Stripe afin d’améliorer leur flexibilité et leur extensibilité. ### Radar Vous pouvez définir des règles Radar pour [faire référence à des valeurs de métadonnées](https://docs.stripe.com/radar/rules/reference.md#metadata-attributes) et les utiliser afin de déterminer si une règle déclenche l’action qui lui est associée pour une transaction. #### Effectuer un premier examen des transactions clients Vous pouvez mettre en place un flux qui marque la première transaction d’un [client](https://docs.stripe.com/api/customers.md) pour examen, puis mettre à jour les informations du client afin de ne pas examiner les transactions suivantes. ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d "name=Jenny Rosen" \ -d "metadata[verified_customer]=false" ``` `Review if ::customer:verified_customer:: != 'true'` ```curl curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \ -u "<>:" \ -d "metadata[verified_customer]=true" ``` Stripe ne déclenche cette règle pour les paiements que si `verified_customer` est défini sur `false` pour le client. Les clients pour lesquels ce paramètre est réglé sur `true` ne sont pas concernés. #### Règles de tests fractionnés Vous pouvez utiliser des métadonnées avec Radar pour créer des scénarios de test A/B pour les nouvelles règles. Cela vous permet d’évaluer l’efficacité d’une nouvelle règle avant de la mettre en œuvre pour l’ensemble de votre clientèle. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=2000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]=true" \ -d "metadata[experiment_group]=treatment" ``` ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=2000 \ -d currency=usd \ -d "automatic_payment_methods[enabled]=true" \ -d "metadata[experiment_group]=control" ``` `Block if ::experiment_group:: = 'treatment' and :card_funding: = 'prepaid'` Stripe déclenche cette règle uniquement pour les paiements que vous désignez comme faisant partie du groupe de traitement. Cela n’affecte pas les paiements dont le paramètre `experiment_group` est défini sur `control`. ### L’API Search Utilisez l’[API Search](https://docs.stripe.com/search.md#metadata) pour interroger et filtrer les résultats en fonction des métadonnées que vous avez définies pour les [objets pris en charge](https://docs.stripe.com/search.md#supported-query-fields-for-each-resource) que vous recherchez. Par exemple, vous pouvez suivre vos clients « premium » en ajoutant des métadonnées à l’objet [Customer](https://docs.stripe.com/api/customers.md). Pour leur proposer des promotions exclusives, utilisez l’API Search en vue d’identifier les clients marqués comme `premium`, puis contactez-les pour leur proposer la promotion. ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d "name=Jenny Rosen" \ -d "metadata[service_tier]=premium" ``` ```curl curl -G https://api.stripe.com/v1/customers/search \ -u "<>:" \ --data-urlencode "query=metadata['service_tier']:'premium'" ``` Les objets doivent être [indexés](https://docs.stripe.com/search.md#data-freshness) pour apparaître dans les résultats de l’API Search. Ils n’apparaîtront pas dans les résultats de recherche tant que l’indexation ne sera pas terminée.