Suchen

Suchen Sie nach Objekten in Ihren Stripe-Daten.

Einige API-Referenzen der obersten Ebene unterstützen den Abruf mit API-Suchmethoden. Sie können die Such-APIs verwenden, um Ihre Stripe-Objekte auf flexible Weise abzurufen. Die Suche ist eine schnellere Alternative zum Paginieren aller Ressourcen. Um eine Suchabfrage zu erstellen, überprüfen Sie die Sprache der Suchabfrage und verweisen Sie auf die Abfragefelder der Ressource:

Beschränkungen

Mindest-API-Version

Für die Verwendung der Suche ist mindestens die API-Version 2020-08-27 erforderlich. Lesen Sie unseren Leitfaden für API-Upgrades, um mehr über diese zu erfahren. Um die Suche ohne API-Upgrade Ihres Kontos zu verwenden, können Sie die API-Version für eine einzelne Anfrage überschreiben, indem Sie den Anfrage-Header Stripe-Version festlegen:

Command Line

-H "Stripe-Version: 2025-04-30.basil"

Lesen Sie unseren SDK-Leitfaden zum Überschreiben einer API-Version bei Verwenden einer Bibliothek.

Datenaktualität

Verwenden Sie die Suche nicht für Lesen-nach-Schreiben-Abläufe (z. B. sofort nach der Zahlungsabwicklung), weil die Daten nicht sofort für die Suche verfügbar sind. Unter normalen Betriebsbedingungen sind die Daten innerhalb von einer Minute für die Suche verfügbar. Die Ausbreitung neuer oder aktualisierter Daten kann sich ausfallbedingt weiter verzögern.

Verwenden Sie für Lesen-nach-Schreiben-Abläufe, die eine sofortige Datenverfügbarkeit erfordern, die verschiedenen Listen-APIs, z. B. Auflisten von Rechnungen). Bei diesen APIs gelten keine der oben erwähnten Verfügbarkeitsverzögerungen.

Daten stimmen nicht überein

In einigen Fällen stimmen die Daten, die Sie zum Auffinden von Suchergebnissen verwenden, möglicherweise nicht mit den Ergebnissen überein, die Sie erhalten. Dies kann passieren, weil die Search API mithilfe einer zwischengespeicherten Version des status des PaymentIntent filtert, jedoch Daten basierend auf der neuesten Version des PaymentIntent zurückgibt.

Wenn Sie zum Beispiel die Search Payment Intents API nach PaymentIntents mit dem Status requires_capture abfragen, werden möglicherweise einige PaymentIntents mit dem Status succeeded zurückgegeben. Dies geschieht, weil die Search API zwischengespeicherte PaymentIntents mit dem älteren Status requires_capture findet, aber den aktuellen Status succeeded in den Ergebnissen zurückgibt.

Ratenbegrenzungen

Wir wenden eine Ratenbegrenzung von bis zu 20 Lesevorgängen pro Sekunde an, die für alle Suchendpunkte im Live-Modus und in Testumgebungen gilt. Die Grenzwerte für den Live-Modus und die Testumgebung werden getrennt erfasst. Unter Berücksichtigung der Ratenbegrenzung ist Sigma für Workloads, bei denen Sie Analysen für eine oder mehrere API-Ressourcen ausführen müssen, viel effizienter. Für Workloads, bei denen Sie einen großen Teil Ihrer API-Ressourcen exportieren müssen, ist unser Data Pipeline-Produkt effizienter.

Regionale Verfügbarkeit

Die Suche ist für Händler in Indien nicht verfügbar.

Test-Uhren-Objekte in Liste aller Ergebnisse ausgelassen

Stripe-Listen-APIs (wie Listen-Rechnungen) lassen von Test-Uhren generierte Ergebnisse für alle Listenanfragen. Um Ergebnisse anzuzeigen, die von Test-Uhren in diesen Fällen generiert werden, müssen Sie Ergebnisse innerhalb eines bestimmten übergeordneten Elements wie test_clock, customer oder subscription anfordern.

GET /v1/invoices gibt zum Beispiel keine von einer Test-Uhr generierten Rechnungen zurück, aber GET /v1/invoices/{customer_id} gibt alle Rechnungen für diesen Kunden/diese Kundin zurück, einschließlich derjenigen, die von der Test-Uhr generiert wurden.

Ebenso können Sie in diesem Beispiel eine Test-Uhr-ID angeben, um alle Rechnungen im Zusammenhang mit dieser Test-Uhr abzurufen, oder Sie können eine Abonnement-ID angeben, um alle Rechnungen zurückzugeben, die für dieses Abonnement in Rechnung gestellt wurden, einschließlich der von der Test-Uhr generierten Rechnungen.

Beispiele

Hier sind einige Beispiele dafür, was Sie mit der Search Charges API und der Search PaymentIntents API tun können:

Suche nach Zahlungen anhand der Metadaten

Suchen Sie nach Zahlungen basierend auf einem übereinstimmenden nutzerdefinierten Metadatenwert.

Suche nach Zahlungen anhand der letzten vier Ziffern

Suchen Sie nach Zahlungen basierend auf Übereinstimmung der letzten vier Ziffern der für die Zahlung verwendeten Karte.

Kundensuche auf Basis der E-Mail-Adresse

Suchen Sie nach Kund/innen basierend auf einer übereinstimmenden E-Mail-Adresse.

Negationsfilter

Suchen Sie nach PaymentIntents, deren Währung nicht USD ist.

Numerischer Filter

Filtern Sie nach Rechnungsobjekten, deren Wert für total größer als 1.000 ist.

Kombination mehrerer Filter

Suchen Sie nach Zahlungen basierend auf einer Kombination aus übereinstimmenden Metadaten und Währung.

Sprache für Suchabfragen

Abfragestruktur und -terminologie

Eine Abfrage-clause besteht aus einem field, gefolgt von einem operator, auf den ein value folgt:

Klausel	`email:"amy@rocketrides.io"`
Feld	`email`
Operator	`:`
Wert	`amy@rocketrides.io`

Sie können bis zu 10 Abfrageklauseln in einer Suche kombinieren, indem Sie sie entweder durch ein Leerzeichen trennen oder die Schlüsselwörter AND oder OR verwenden (Groß-/Kleinschreibung wird nicht berücksichtigt). Sie können AND und OR nicht in derselben Abfrage kombinieren. Darüber hinaus gibt es keine Möglichkeit, bestimmte logische Operatoren durch Klammern zu priorisieren. Standardmäßig kombiniert die API Klauseln mit AND-Logik.

Die folgende Beispielabfrage email:"amy@rocketrides.io" metadata["key"]:"value" gleicht Datensätze sowohl basierend auf der E-Mail-Adresse amy@rocketrides.io als auch auf dem in den Metadaten enthaltenen key mit dem Wert value ab.

Erstellen einer Abfrage mit einer ausschließenden Klausel

Sie können Abfrageklauseln mithilfe des Zeichens - negieren. Beispiel: Die folgende Suche gibt Datensätze zurück, die nicht mit der E-Mail-Adresse amy@rocketrides.io übereinstimmen.

-email:"amy@rocketrides.io"

Feldtypen, Abgleich von Teilzeichenfolgen und numerische Komparatoren

Alle Suchfelder unterstützen den exakten Abgleich mithilfe des Zeichens :. Einige Felder wie email und name unterstützen den Abgleich von Teilzeichenfolgen. Bestimmte andere Felder wie amount unterstützen numerische Komparatoren wie > und <.

Jedes Feld umfasst einen Typ, der die im Feld anwendbaren Operationen definiert. Eine vollständige Liste der verfügbaren Felder finden Sie unter Unterstützte Abfragefelder für jede Ressource.

Bei der Verwendung eines nicht unterstützten Operators (z. B. > bei einer Zeichenfolge) wird ein Fehler zurückgegeben.

Typ Operatoren

Token Genaue Übereinstimmung (keine Berücksichtigung der Groß-/Kleinschreibung)

Typ	Operatoren
Token	Genaue Übereinstimmung (keine Berücksichtigung der Groß-/Kleinschreibung)
Zeichenfolge	Genaue Übereinstimmung, Teilzeichenfolge (keine Berücksichtigung der Groß-/Kleinschreibung) Eine exakte Übereinstimmung mit einem Zeichenkettentyp gibt jeden Datensatz zurück, der alle Wörter der Abfrage in derselben Reihenfolge enthält. Beispielsweise würde die Abfrage `name:"one two three"` zu einem Ergebnis mit dem Namen „ein zwei drei“ als auch zu einem Ergebnis mit dem Namen „eins zwei drei vier“ passen.
Numerisch	Genaue Übereinstimmung, größer als und kleiner als

Zeichenfolge

Genaue Übereinstimmung, Teilzeichenfolge (keine Berücksichtigung der Groß-/Kleinschreibung)

Eine exakte Übereinstimmung mit einem Zeichenkettentyp gibt jeden Datensatz zurück, der alle Wörter der Abfrage in derselben Reihenfolge enthält. Beispielsweise würde die Abfrage name:"one two three" zu einem Ergebnis mit dem Namen „ein zwei drei“ als auch zu einem Ergebnis mit dem Namen „eins zwei drei vier“ passen.

Numerisch Genaue Übereinstimmung, größer als und kleiner als

Anführungszeichen

Die Werte von Zeichenfolgen müssen in Anführungszeichen eingeschlossen sein. Bei numerischen Werten sind Anführungszeichen optional. Beispiel:

currency:"usd" bedeutet, dass Anführungszeichen erforderlich sind.
payment_method_details.card.last4:1234 bedeutet, dass Anführungszeichen optional sind.

Sie können Anführungszeichen innerhalb von Anführungszeichen durch einen umgekehrten Schrägstrich (\) mit Escapezeichen versehen.

description:"the story called \"The Sky and the Sea.\""

Metadaten

Sie können Metadaten durchsuchen, die Sie Objekten hinzugefügt haben, die diese unterstützen.

Verwenden Sie das folgende Format, um eine Klausel für eine Metadatensuche zu erstellen: metadata["<field>"]:"<value>".

Das folgende Beispiel zeigt, wie eine Klausel erstellt wird, die nach Datensätzen mit der Donation-ID “asdf-jkl” sucht: metadata["donation-id"]:"asdf-jkl".

Sie können abfragen, ob ein Metadatenschlüssel für ein Objekt vorliegt. Der folgende Abschnitt würde alle Datensätze abgleichen, bei denen donation-id ein Metadatenschlüssel ist. -metadata["donation-id"]:null

Suchsyntax

Die folgende Tabelle listet die Syntax auf, die Sie zum Erstellen einer Abfrage verwenden können.

Syntax	Nutzung	Beschreibung	Beispiele
`:`	`field:value`	Genaue Übereinstimmung (keine Berücksichtigung der Groß-/Kleinschreibung)	`currency:"eur"` gibt Datensätze zurück, in denen die Währung nur „EUR“ ist, wobei die Groß-/Kleinschreibung nicht beachtet wird
`AND`, `and`	`field:value1 AND field:value2`	Die Abfrage gibt nur Datensätze zurück, die (ohne Rücksicht auf Groß-/Kleinschreibung) mit beiden Klauseln übereinstimmen.	`status:"active" AND amount:500`
`OR`, `or`	`field:value1 OR field:value2`	Die Abfrage gibt Datensätze zurück, die (ohne Rücksicht auf Groß-/Kleinschreibung) mit einer der beiden Klauseln übereinstimmen.	`currency:"usd" OR currency:"eur"`
`-`	`-field:value`	Gibt Datensätze zurück, die mit der Klausel nicht übereinstimmen	`-currency:"jpy"` gibt Datensätze zurück, die nicht in JPY angegeben sind
`NULL`, `null`	`field:null`	Ein spezielles Token, das für das Vorhandensein eines Felds verwendet wird (ohne Berücksichtigung der Groß-/Kleinschreibung)	`url:null` gibt Datensätze zurück, bei denen das URL-Feld leer ist.
`\`	`" \"\""`	Escapezeichen für Anführungszeichen innerhalb von Anführungszeichen	`description:"the story called \"The Sky and the Sea.\""`
`~`	`field~value`	Teilzeichenfolgen-Match-Operator (Teilzeichenfolgen müssen mindestens 3 Zeichen lang sein)	`email~"amy"` gibt Datensätze mit „amy@rocketrides.io“ und „xamy“ zurück.
`>`, `<`, `=`	`field<value` `field>value` `field>=value` `field<=value`	Operatoren Größer als/Kleiner	`amount>="10"` gibt Objekte mit einem Betrag von 10 oder größer zurück.

Unterstützte Abfragefelder für jede Ressource

Abfragefelder für Zahlungen

Feld	usage	Typ (Token, Zeichenkette, numerisch)
amount	`amount>1000`	Numerisch
billing_details.address.postal_code	`billing_details.address.postal_code:12345`	Token
created	`created>1620310503`	Numerisch
currency	`currency:"usd"`	Token
customer	`customer:"cus_123"`	Token
Angefochten	`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
Zurückerstattet	`refunded:"true"`	Token
status	`status:"succeeded"`	Token

Als SOURCE verwenden Sie card, card_present, interac_present oder eine der von Terminal unterstützten zusätzlichen Zahlungsmethoden. Verwenden Sie card für Online-Zahlungen, interac_present für Terminal-Card-Present-Zahlungen für das Interac-Netzwerk und card_present für andere Terminal-Card-Present-Zahlungen.

Bei der Abfrage von Terminal-bezogenen Feldern, die nicht für Karten spezifiziert sind, wie reader und location, können Sie auch andere Zahlungsmethoden wie wechat_pay verwenden.

Das Feld disputed akzeptiert nur die Token „true“ und „false“, die das Vorhandensein von Streitigkeiten anzeigen.

refunded:"true" filtert nach vollständig zurückerstatteten Zahlungen, refunded:"false" filtert nach Zahlungen, die noch gar nicht zurückerstattet wurden oder teilweise zurückerstattet wurden, und refunded:null filtert nach nicht zurückerstatteten Zahlungen.

Abfragefelder für Kundinnen/Kunden

Feld	usage	Typ (Token, Zeichenkette, numerisch)
created	`created>1620310503`	Numerisch
email	`email~"amyt"`	Zeichenfolge
metadata	`metadata["key"]:"value"`	Token
name	`name~"amy"`	Zeichenfolge
phone	`phone:"+19999999999"`	Zeichenfolge

Abfragefelder für Rechnungen

Feld	usage	Typ (Token, Zeichenkette, numerisch)
created	`created>1620310503`	Numerisch
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"`	Zeichenfolge
receipt_number	`receipt_number:"RECEIPT-123"`	Zeichenfolge
status	`status:"open"`	Zeichenfolge
subscription	`subscription:"SUBS-123"`	Zeichenfolge
total	`total>1000`	Numerisch

Abfragefelder für PaymentIntents

Feld	usage	Typ (Token, Zeichenkette, numerisch)
amount	`amount>1000`	Numerisch
created	`created>1620310503`	Numerisch
currency	`currency:"usd"`	Token
customer	`customer:"cus_123"`	Token
metadata	`metadata["key"]:"value"`	Token
status	`status:"succeeded"`	Token

Abfragefelder für Preise

Feld	usage	Typ (Token, Zeichenkette, numerisch)
active	`active:"true"`	Token
currency	`currency:"usd"`	Token
lookup_key	`lookup_key:"standard_monthly"`	Zeichenfolge
metadata	`metadata["key"]:"value"`	Token
product	`product:"prod_123"`	Zeichenfolge
Typ	`type:"recurring"`	Token

Abfragefelder für Produkte

Feld	usage	Typ (Token, Zeichenkette, numerisch)
active	`active:"true"`	Token
description	`description~"t-shirts"`	Zeichenfolge
metadata	`metadata["key"]:"value"`	Token
name	`name~"amy"`	Zeichenfolge
shippable	`shippable:"true"`	Token
url	`url~"/dinosaur_swag"`	Zeichenfolge

Abfragefelder für Abonnements

Feld	usage	Typ (Token, Zeichenkette, numerisch)
created	`created>1620310503`	Numerisch
metadata	`metadata["key"]:"value"`	Token
status	`status:"active"`	Token
canceled_at	`canceled_at>1721521117`	Numerisch