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: 2024-11-20.acacia"

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.

For read-after-write flows that require immediate data availability, use the various list APIs, such as List invoices). These APIs aren’t subject to the availability delays mentioned above.

Ratenbegrenzungen

Wir erlauben einen Grenzwert von bis zu 20 Lesevorgängen pro Sekunde. Dies gilt für alle Test-Endpoints, sowohl im Live-Modus als auch im Testmodus. Die Grenzwerte für den Live- und den Testmodus werden getrennt erfasst. Bei Vorgängen, bei denen Sie Analysen für eine oder mehrere API-Ressourcen ausführen müssen, und wenn Sie die Ratenbegrenzung berücksichtigen, ist Sigma viel effizienter. Vorgänge, bei denen Sie einen Großteil Ihrer API-Ressource exportieren müssen, ist unser Produkt Data Pipeline besser geeignet.

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 mehrere Abfrageklauseln in einer Suche kombinieren, indem Sie sie entweder durch Leerzeichen trennen oder die Schlüsselwörter AND oder OR (keine Berücksichtigung der Groß-/Kleinschreibung) verwenden. Sie können AND und OR nicht in derselben Abfrage kombinieren. Außerdem besteht nicht die Möglichkeit, bestimmten logischen Operatoren durch Klammern Vorrang einzuräumen. Standardmäßig kombiniert die API Klauseln mit der 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
Zurückerstattet	`refunded:"true"`	Token
status	`status:"succeeded"`	Token

Verwenden Sie für SOURCE card, card_present oder interac_present. Verwenden Sie card für Online-Zahlungen, interac_present für Card-Present-Zahlungen über Terminal im Interac-Netwerk und card_present für andere Card-Present-Zahlungen über Terminal.

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

refunded:"true" filtert für vollständig erstattete Gebühren, refunded:"false" filtert für teilweise erstattete Gebühren und refunded:null filtert für nicht erstattete Gebühren.

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