# Rechercher Recherchez des objets dans vos données Stripe. Certaines ressources API de niveau supérieur prennent en charge la récupération d’informations via des méthodes de recherche sur l’API . Vous pouvez utiliser les API de recherche pour récupérer vos objets Stripe comme bon vous semble. Cette méthode s’avère plus efficace que de [parcourir page par page](https://docs.stripe.com/api/pagination.md) l’ensemble des ressources. Pour créer une requête de recherche, vérifiez le [langage de requête de recherche](https://docs.stripe.com/search.md#search-query-language) et référencez les champs de requête de la ressource : - [Champs de requête pour les paiements](https://docs.stripe.com/search.md#query-fields-for-charges) - [Champs de requête pour les clients](https://docs.stripe.com/search.md#query-fields-for-customers) - [Champs de requête pour les factures](https://docs.stripe.com/search.md#query-fields-for-invoices) - [Champs de requête pour les PaymentIntents](https://docs.stripe.com/search.md#query-fields-for-paymentintents) - [Champs de requête pour les tarifs](https://docs.stripe.com/search.md#query-fields-for-prices) - [Champs de requête pour les produits](https://docs.stripe.com/search.md#query-fields-for-products) - [Champs de requête pour les abonnements](https://docs.stripe.com/search.md#query-fields-for-subscriptions) ## Limitations ### Version minimale de l’API La version minimale de l’API prise en charge pour utiliser la recherche est `2020-08-27`. Pour en savoir plus sur les mises à niveau, consultez notre [guide consacré aux mises à niveau de l’API](https://docs.stripe.com/upgrades.md). Pour utiliser la fonction de recherche sans mettre à niveau la version de l’API de votre compte, vous pouvez remplacer cette dernière via une unique requête en définissant un en-tête de requête `Stripe-Version` : ```bash -H "Stripe-Version: 2026-04-22.dahlia" ``` Consultez notre guide sur les [SDK](https://docs.stripe.com/sdks.md#versioning) pour savoir comment remplacer une version d’API lors de l’utilisation d’une bibliothèque. ### Actualisation des données N’utilisez pas la recherche pour les flux de lecture après écriture (par exemple, effectuer une recherche immédiatement après un paiement) car les données ne seront pas immédiatement disponibles pour la recherche. Dans des conditions de fonctionnement normales, les données sont consultables en moins d’1 minute. En cas de panne, la propagation de nouvelles données ou de données mises à jour peut prendre plus de temps. Pour les flux de lecture après écriture qui nécessitent une disponibilité immédiate des données, utilisez les différentes API List, telles que [List invoices](https://docs.stripe.com/api/invoices/list.md)). Ces API ne sont pas soumises aux délais de disponibilité mentionnés ci-dessus. ### Données incohérentes Dans certains cas, les données que vous utilisez pour trouver des résultats de recherche peuvent ne pas correspondre aux résultats que vous obtenez. Cela peut se produire parce que l’API Search filtre à l’aide d’une version mise en cache de l’attribut `status` du PaymentIntent, mais renvoie des données basées sur la dernière version du PaymentIntent. Par exemple, si vous interrogez l’[API Search Payment Intents](https://docs.stripe.com/api/payment_intents/search.md) pour trouver des PaymentIntents à l’état `requires_capture`, elle peut renvoyer des PaymentIntents à l’état `succeeded`. Cela est dû au fait que l’API Search trouve les PaymentIntents mis en cache qui ont l’ancien état `requires_capture`, mais renvoie l’état actuel `succeeded` dans les résultats. ### Limites de débit Nous appliquons une [limite d’appels](https://docs.stripe.com/rate-limits.md) de 20 opérations de lecture par seconde, qui s’applique à tous les points de terminaison de recherche en mode production et dans les environnements de test. Les limites en mode production et dans les environnements de test sont distinctes. Compte tenu de cette limite, [Sigma](https://docs.stripe.com/stripe-data/how-sigma-works.md) est beaucoup plus efficace pour les charges de travail qui nécessitent d’effectuer des analyses sur une ou plusieurs ressources API. Pour les charges de travail qui nécessitent d’exporter une grande partie de vos ressources API, notre produit [Data Pipeline](https://docs.stripe.com/stripe-data/access-data-in-warehouse.md) est plus efficace. ### Disponibilité régionale La fonction de recherche n’est pas disponible pour les entreprises établies en Inde. ### Objets de l’horloge de simulation omis dans la liste de tous les résultats Les API de liste de Stripe (telles que [Liste de factures](https://docs.stripe.com/api/invoices/list.md)) omettent les résultats générés par les horloges de simulation pour toutes les requêtes de liste. Pour voir les résultats générés par les horloges de simulation dans ces cas, vous devez demander des résultats dans un parent spécifique, tel que `test_clock`, `customer` ou `subscription`. Par exemple, `GET /v1/invoices` ne renverra pas les factures générées par l’horloge de simulation, mais `GET {customer_id}` renverra toutes les factures pour ce client, y compris celles qui sont générées par l’horloge de simulation. De même, vous pouvez spécifier un identifiant d’horloge de simulation dans cet exemple pour obtenir toutes les factures liées à cette horloge, ou spécifier un identifiant d’abonnement pour obtenir toutes les factures relatives à cet abonnement, y compris les factures générées par l’horloge de simulation. ### Pagination Dans de rares cas, la pagination d’un jeu de résultats peut réorganiser certains enregistrements, ce qui entraîne leur absence ou leur duplication sur une page. Si vous rencontrez ce problème, contactez-nous via le formulaire du [service de support Stripe](https://support.stripe.com). ## Exemples Voici quelques exemples de ce que vous pouvez faire avec l’[API Search Charges](https://docs.stripe.com/api/charges/search.md) et l’[API Search PaymentIntents](https://docs.stripe.com/api/payment_intents/search.md) : ### Recherche des paiements en fonction de métadonnées Recherchez les paiements correspondant à une valeur des métadonnées personnalisée. ```curl curl -G https://api.stripe.com/v1/charges/search \ -u "<>:" \ --data-urlencode "query=metadata['key']:'value'" ``` ### Recherche des paiements en fonction des 4 derniers chiffres Recherchez les paiements correspondant aux 4 derniers chiffres de la carte bancaire utilisée pour le paiement. ```curl curl -G https://api.stripe.com/v1/charges/search \ -u "<>:" \ --data-urlencode "query=payment_method_details.card.last4:4242" ``` ### Recherche de clients en fonction de leur adresse e-mail Recherchez des clients correspondant à une adresse e-mail. ```curl curl -G https://api.stripe.com/v1/customers/search \ -u "<>:" \ --data-urlencode "query=email:'sally@rocketrides.io'" ``` ### Filtre d’exclusion Recherchez les PaymentIntents pour lesquels la devise n’est pas USD. ```curl curl -G https://api.stripe.com/v1/payment_intents/search \ -u "<>:" \ --data-urlencode "query=-currency:'usd'" ``` ### Filtre numérique Filtrez les objets Invoice dont le `total` est supérieur à 1000. ```curl curl -G https://api.stripe.com/v1/invoices/search \ -u "<>:" \ -d "query=total>1000" ``` ### Combinaison de plusieurs filtres Recherchez les paiements correspondant à une combinaison de métadonnées et de devises. ```curl curl -G https://api.stripe.com/v1/charges/search \ -u "<>:" \ --data-urlencode "query=metadata['key']:'value' AND currency:'usd'" ``` ## Langage de requête de recherche ### Structure et terminologie des requêtes Une `clause` de requête est composée d’un champ `field` suivi d’un opérateur `operator`, lui-même suivi d’une valeur `value` : | | | | | clause | `email:"amy@rocketrides.io"` | | champ | `email` | | opérateur | `:` | | valeur | `amy@rocketrides.io` | Vous pouvez associer jusqu’à 10 clauses de requête dans une recherche en les séparant par un espace ou en utilisant les mots-clés `AND` ou `OR` (insensibles à la casse). Vous ne pouvez pas associer `AND` et `OR` dans la même requête. De plus, il n’est pas possible d’utiliser des parenthèses pour donner la priorité à certains opérateurs logiques. Par défaut, l’API associe des clauses avec la logique `AND`. L’exemple de requête `email:"amy@rocketrides.io" metadata["key"]:"value"` renvoie les enregistrements pour lesquels l’adresse e-mail est amy@rocketrides.io et les métadonnées de l’enregistrement comprennent `key` avec une valeur égale à `value`. ### Créer une requête qui ne correspond pas à une clause Vous pouvez exclure des clauses d’une requête en utilisant le caractère `-`. Par exemple, la recherche suivante renvoie les enregistrements qui ne correspondent pas à l’adresse e-mail `amy@rocketrides.io`. `-email:"amy@rocketrides.io"` ### Types de champs, correspondance de sous-chaînes et comparateurs numériques Le caractère `:` permet à chaque champ de recherche de prendre en charge la correspondance exacte. Certains champs, tels que `email` et `name`, prennent en charge la correspondance de sous-chaîne. Certains autres champs, tels que `amount`, prennent en charge les comparateurs numériques comme `>` et `<`. Le type d’un champ détermine les opérations que vous pouvez utiliser sur ce champ. Pour obtenir la liste complète des champs disponibles, consultez la section [Champs de requête pris en charge pour chaque ressource](https://docs.stripe.com/search.md#supported-query-fields-for-each-resource). L’utilisation d’un opérateur non pris en charge, comme le fait de spécifier supérieur à (`>`) sur une chaîne, renvoie une erreur. | type | opérateurs | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | token | correspondance exacte (sans distinction de casse) | | chaîne | correspondance exacte, sous-chaîne (sans distinction de casse) Une correspondance exacte du type de chaîne renvoie tous les enregistrements contenant l’ensemble des mots de la requête dans le même ordre. Par exemple, la requête `name:"one two three"` afficherait les enregistrements contenant “one two three” et “one two three four”. | | numérique | correspondance exacte, supérieur à et inférieur à | ### Guillemets Vous devez placer les valeurs de type chaîne entre guillemets. Les guillemets sont facultatifs pour les valeurs numériques. Par exemple : - `currency:"usd"` signifie que les guillemets sont obligatoires. - `payment_method_details.card.last4:1234` indique que les guillemets sont facultatifs. Vous pouvez échapper les guillemets à l’intérieur de guillemets avec une barre oblique inverse (`\`). `description:"l'histoire s'intitule \"Le ciel et la mer.\""` ### Métadonnées Vous pouvez effectuer des recherches sur des [métadonnées](https://docs.stripe.com/api/metadata.md) que vous avez ajoutées aux objets qui les prennent en charge. Utilisez le format suivant pour créer une clause pour une recherche de métadonnées : `metadata[""]:""`. La clause suivante montre comment créer une clause qui recherche les enregistrements ayant un numéro de don de “asdf-jkl”: `metadata["id-don"]:"asdf-jkl"`. Vous pouvez rechercher une clé de métadonnées sur un objet. La clause suivante renvoie tous les enregistrements pour lesquels `donation-id` est une clé de métadonnées. `-metadata["donation-id"]:null` ### Syntaxe de Search Le tableau suivant répertorie la syntaxe que vous pouvez utiliser pour créer une requête. | Syntaxe | Utilisation | Description | Exemples | | -------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `:` | `field:value` | Opérateur de correspondance exacte (insensible à la casse) | `currency:"eur"` renvoie les enregistrements dont la devise est exactement « EUR » (la comparaison ne tient pas compte de la casse) | | `AND`, `and` | `field:value1 AND field:value2` | La requête renvoie uniquement les enregistrements qui correspondent aux deux clauses (sans distinction de casse) | `status:"active" AND amount:500` | | `OR`, `or` | `field:value1 OR field:value2` | La requête renvoie les enregistrements qui correspondent à l’une ou l’autre des clauses (sans distinction de casse) | `currency:"usd" OR currency:"eur"` | | `-` | `-field:value` | Renvoie les enregistrements qui ne correspondent pas à la clause | `-currency:"jpy"` renvoie les enregistrements dont la devise n’est pas le JPY | | `NULL`, `null` | `field:null` | Token spécifique utilisé pour la présence du champ (sans distinction de casse). | `url:null` renvoie les enregistrements pour lesquels le champ URL est vide | | `\` | `" \"\""` | Échapper des guillemets au sein de guillemets | `description:"l'histoire s'intitule \"Le ciel et la mer.\""` | | `~` | `field~value` | Opérateur de correspondance des sous-chaînes (les sous-chaînes doivent comporter au moins 3 caractères) | `email~"amy"` renvoie des correspondances pour amy@rocketrides.io et xamy | | `>`, `<`, `=` | - `fieldvalue` - `field>=value` - `field<=value` | Opérateurs supérieur à/inférieur à | `amount>="10"` renvoie les objets dont le montant est supérieur ou égal à 10 | ## Champs de requête pris en charge pour chaque ressource ### Champs de requête pour les paiements | Champ | usage | Type (token, chaîne, valeur numérique) | | --------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------- | | amount | `amount>1000` | numérique | | billing_details.address.postal_code | `billing_details.address.postal_code:12345` | token | | created | `created>1620310503` | numérique | | currency | `currency:"usd"` | token | | customer | `customer:"cus_123"` | token | | disputed | `disputed:"true"` | token | | metadata | `metadata["key"]:"value"` | token | | payment_method_details.{{SOURCE}}.last4 | `payment_method_details.card.last4:1234` | token | | payment_method_details.{{SOURCE}}.exp_month | `payment_method_details.card_present.exp_month:12` | token | | payment_method_details.{{SOURCE}}.exp_year | `payment_method_details.interac_present.exp_year:2022` | token | | payment_method_details.{{SOURCE}}.brand | `payment_method_details.card.brand:"visa"` | token | | payment_method_details.{{SOURCE}}.fingerprint | `payment_method_details.card.fingerprint:"fp"` | token | | payment_method_details.{{SOURCE}}.reader | `payment_method_details.wechat_pay.reader:"tmr_FDOt2wlRZEdpd7"` | token | | payment_method_details.{{SOURCE}}.location | `payment_method_details.wechat_pay.location:"tml_FBakXQG8bQk4Mm"` | token | | refunded | `refunded:"true"` | token | | status | `status:"succeeded"` | token | Pour `SOURCE`, utilisez `card` , `card_present`, `interac_present` ou l’un des [moyens de paiement supplémentaires pris en charge par Terminal](https://docs.stripe.com/terminal/payments/additional-payment-methods.md). Utilisez `card` pour les paiements en ligne, `interac_present` pour les paiements Terminal par carte sur le réseau Interac et `card_present` pour les autres paiements Terminal par carte. Lorsque vous interrogez les champs liés à Terminal qui ne sont pas spécifiques aux cartes, comme `reader` et `location`, vous pouvez également utiliser d’autres moyens de paiement comme `wechat_pay`. Le champ `disputed` accepte uniquement les tokens « true » et « false » et indique la présence de litiges. Filtres `refunded:"true"` pour les paiements intégralement remboursés, filtres `refunded:"false"` pour les paiements non remboursés ou partiellement remboursés et filtres `refunded:null` pour les paiements non remboursables. ### Champs de requête pour les clients | Champ | usage | Type (token, chaîne, valeur numérique) | | -------- | ------------------------- | -------------------------------------- | | created | `created>1620310503` | numérique | | email | `email~"amyt"` | chaîne | | metadata | `metadata["key"]:"value"` | token | | name | `name~"amy"` | chaîne | | phone | `phone:"+19999999999"` | chaîne | ### Champs de requête pour les factures | Champ | usage | Type (token, chaîne, valeur numérique) | | ---------------------------- | -------------------------------------------------------------- | -------------------------------------- | | created | `created>1620310503` | numérique | | currency | `currency:"usd"` | token | | customer | `customer:"cus_123"` | token | | last_finalization_error_code | `last_finalization_error_code:"customer_tax_location_invalid"` | token | | last_finalization_error_type | `last_finalization_error_type:"invalid_request_error"` | token | | metadata | `metadata["key"]:"value"` | token | | number | `number:"MYSHOP-123"` | chaîne | | receipt_number | `receipt_number:"RECEIPT-123"` | chaîne | | status | `status:"open"` | chaîne | | subscription | `subscription:"SUBS-123"` | chaîne | | total | `total>1000` | numérique | ### Champs de requête pour les PaymentIntents | Champ | usage | Type (token, chaîne, valeur numérique) | | -------- | ------------------------- | -------------------------------------- | | amount | `amount>1000` | numérique | | created | `created>1620310503` | numérique | | currency | `currency:"usd"` | token | | customer | `customer:"cus_123"` | token | | metadata | `metadata["key"]:"value"` | token | | status | `status:"succeeded"` | token | ### Champs de requête pour les tarifs | Champ | usage | Type (token, chaîne, valeur numérique) | | ---------- | ------------------------------- | -------------------------------------- | | active | `active:"true"` | token | | currency | `currency:"usd"` | token | | lookup_key | `lookup_key:"standard_monthly"` | chaîne | | metadata | `metadata["key"]:"value"` | token | | product | `product:"prod_123"` | chaîne | | type | `type:"recurring"` | token | ### Champs de requête pour les produits | Champ | usage | Type (token, chaîne, valeur numérique) | | ----------- | ------------------------- | -------------------------------------- | | active | `active:"true"` | token | | description | `description~"t-shirts"` | chaîne | | metadata | `metadata["key"]:"value"` | token | | name | `name~"amy"` | chaîne | | shippable | `shippable:"true"` | token | | url | `url~"/dinosaur_swag"` | chaîne | ### Champs de requête pour les abonnements | Champ | usage | Type (token, chaîne, valeur numérique) | | ----------- | ------------------------- | -------------------------------------- | | created | `created>1620310503` | numérique | | metadata | `metadata["key"]:"value"` | token | | status | `status:"active"` | token | | canceled_at | `canceled_at>1721521117` | numérique |