Accéder directement au contenu
Créez un compte
ou
connecter-vous
Logo de la documentation Stripe
/
Demander à l'assistant IA
Créez un compte
Connectez-vous
Démarrer
Paiements
Revenus
Plateformes et places de marché
Gestion de fonds
Ressources pour les développeurs
Aperçu
Gestion des versions
Journal des modifications
Mettre à niveau votre version de l'API
Actualiser votre version du SDK
Essentials
SDK
API
    API v2
    Clés API
    En-tête Stripe-Context
    Journal quotidien des modifications
    Limites de débit
    Tests automatiques
    Métadonnées
    Développement des réponses
    Pagination
    Domaines et adresses IP
    Rechercher
    Localisation
    Gestion des erreurs
    Codes d'erreur
Tests
CLI Stripe
Exemples de projets
Outils
Workbench
Dashboard des développeurs
Shell Stripe
Stripe pour Visual Studio Code
Fonctionnalités
Workflows
Destinations d'événements
Alertes d'intégrité de StripeChargements de fichiers
Solutions d'IA
Boîte à outils des agents
Sécurité et confidentialité
Sécurité
Confidentialité
Extensions Stripe
Build Stripe apps
Use apps from Stripe
Partenaires
Partner ecosystem
Certification des partenaires
AccueilRessources pour les développeursAPI

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 l’ensemble des ressources. Pour créer une requête de recherche, vérifiez le langage de requête de recherche et référencez les champs de requête de la ressource :

  • Champs de requête pour les paiements
  • Champs de requête pour les clients
  • Champs de requête pour les factures
  • Champs de requête pour les PaymentIntents
  • Champs de requête pour les tarifs
  • Champs de requête pour les produits
  • Champs de requête pour les abonnements

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. 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 :

Command Line
-H "Stripe-Version: 2025-06-30.basil"

Consultez notre guide sur les SDK 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). 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 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 de débit de 20 opérations par seconde en lecture qui s’applique à tous les endpoints de recherche, en mode production comme en mode test. Ces deux modes ont des limites distinctes. Les limites du mode production et de l’environnement de test sont distinctes. En gardant à l’esprit la limite de débit, pour les tâches où vous devez exécuter des analyses sur une ou plusieurs ressources d’API, Sigma est beaucoup plus efficace. Pour les tâches où vous devez exporter une grande partie de vos ressources API, notre produit Data Pipeline est plus efficace.

Disponibilité régionale

La fonction de recherche n’est pas disponible pour les marchands établis 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) 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.

Exemples

Voici quelques exemples de ce que vous pouvez faire avec l’API Search Charges et l’API Search PaymentIntents :

Recherche des paiements en fonction de métadonnées

Recherchez les paiements correspondant à une valeur des métadonnées personnalisée.

Command Line
cURL
curl -G https://api.stripe.com/v1/charges/search \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ --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.

Command Line
cURL
curl -G https://api.stripe.com/v1/charges/search \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ --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.

Command Line
cURL
curl -G https://api.stripe.com/v1/customers/search \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ --data-urlencode query="email:'sally@rocketrides.io'"

Filtre d’exclusion

Recherchez les PaymentIntents pour lesquels la devise n’est pas USD.

Command Line
cURL
curl -G https://api.stripe.com/v1/payment_intents/search \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ --data-urlencode query="-currency:'usd'"

Filtre numérique

Filtrez les objets Invoice dont le total est supérieur à 1000.

Command Line
cURL
curl -G https://api.stripe.com/v1/invoices/search \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d query="total>1000"

Combinaison de plusieurs filtres

Recherchez les paiements correspondant à une combinaison de métadonnées et de devises.

Command Line
cURL
curl -G https://api.stripe.com/v1/charges/search \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ --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 :

clauseemail:"amy@rocketrides.io"
champemail
opérateur:
valeuramy@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éation d’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.

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.

typeopérateurs
tokencorrespondance 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ériquecorrespondance 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 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["<field>"]:"<value>".

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.

SyntaxeUtilisationDescriptionExemples
:field:valueOpé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, andfield:value1 AND field:value2La requête renvoie uniquement les enregistrements qui correspondent aux deux clauses (sans distinction de casse)status:"active" AND amount:500
OR, orfield:value1 OR field:value2La requête renvoie les enregistrements qui correspondent à l’une ou l’autre des clauses (sans distinction de casse)currency:"usd" OR currency:"eur"
--field:valueRenvoie les enregistrements qui ne correspondent pas à la clause-currency:"jpy" renvoie les enregistrements dont la devise n’est pas le JPY
NULL, nullfield:nullToken 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 guillemetsdescription:"l'histoire s'intitule \"Le ciel et la mer.\""
~field~valueOpé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
>, <, =
  • field<value
  • field>value
  • 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

ChampusageType (token, chaîne, valeur numérique)
amountamount>1000numérique
billing_details.address.postal_codebilling_details.address.postal_code:12345token
createdcreated>1620310503numérique
currencycurrency:"usd"token
customercustomer:"cus_123"token
disputeddisputed:"true"token
metadatametadata["key"]:"value"token
payment_method_details.{{SOURCE}}.last4payment_method_details.card.last4:1234token
payment_method_details.{{SOURCE}}.exp_monthpayment_method_details.card_present.exp_month:12token
payment_method_details.{{SOURCE}}.exp_yearpayment_method_details.interac_present.exp_year:2022token
payment_method_details.{{SOURCE}}.brandpayment_method_details.card.brand:"visa"token
payment_method_details.{{SOURCE}}.fingerprintpayment_method_details.card.fingerprint:"fp"token
payment_method_details.{{SOURCE}}.readerpayment_method_details.wechat_pay.reader:"tmr_FDOt2wlRZEdpd7"token
payment_method_details.{{SOURCE}}.locationpayment_method_details.wechat_pay.location:"tml_FBakXQG8bQk4Mm"token
refundedrefunded:"true"token
statusstatus:"succeeded"token

Pour SOURCE, utilisez card , card_present, interac_present ou l’un des moyens de paiement supplémentaires pris en charge par Terminal. 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

ChampusageType (token, chaîne, valeur numérique)
createdcreated>1620310503numérique
emailemail~"amyt"chaîne
metadatametadata["key"]:"value"token
namename~"amy"chaîne
phonephone:"+19999999999"chaîne

Champs de requête pour les factures

ChampusageType (token, chaîne, valeur numérique)
createdcreated>1620310503numérique
currencycurrency:"usd"token
customercustomer:"cus_123"token
last_finalization_error_codelast_finalization_error_code:"customer_tax_location_invalid"token
last_finalization_error_typelast_finalization_error_type:"invalid_request_error"token
metadatametadata["key"]:"value"token
numbernumber:"MYSHOP-123"chaîne
receipt_numberreceipt_number:"RECEIPT-123"chaîne
statusstatus:"open"chaîne
subscriptionsubscription:"SUBS-123"chaîne
totaltotal>1000numérique

Champs de requête pour les PaymentIntents

ChampusageType (token, chaîne, valeur numérique)
amountamount>1000numérique
createdcreated>1620310503numérique
currencycurrency:"usd"token
customercustomer:"cus_123"token
metadatametadata["key"]:"value"token
statusstatus:"succeeded"token

Champs de requête pour les tarifs

ChampusageType (token, chaîne, valeur numérique)
activeactive:"true"token
currencycurrency:"usd"token
lookup_keylookup_key:"standard_monthly"chaîne
metadatametadata["key"]:"value"token
productproduct:"prod_123"chaîne
typetype:"recurring"token

Champs de requête pour les produits

ChampusageType (token, chaîne, valeur numérique)
activeactive:"true"token
descriptiondescription~"t-shirts"chaîne
metadatametadata["key"]:"value"token
namename~"amy"chaîne
shippableshippable:"true"token
urlurl~"/dinosaur_swag"chaîne

Champs de requête pour les abonnements

ChampusageType (token, chaîne, valeur numérique)
createdcreated>1620310503numérique
metadatametadata["key"]:"value"token
statusstatus:"active"token
canceled_atcanceled_at>1721521117numérique
Cette page vous a-t-elle été utile ?
OuiNon
Besoin d'aide ? Contactez le service Support.
Rejoignez notre programme d'accès anticipé.
Consultez notre log des modifications.
Des questions ? Contactez l'équipe commerciale.
LLM ? Lire llms.txt.
Propulsé par Markdoc