# 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](https://docs.stripe.com/api/pagination.md) aller Ressourcen. Um eine Suchabfrage zu erstellen, überprüfen Sie die [Sprache der Suchabfrage](https://docs.stripe.com/search.md#search-query-language) und verweisen Sie auf die Abfragefelder der Ressource: - [Abfragefelder für Zahlungen](https://docs.stripe.com/search.md#query-fields-for-charges) - [Abfragefelder für Kundinnen/Kunden](https://docs.stripe.com/search.md#query-fields-for-customers) - [Abfragefelder für Rechnungen](https://docs.stripe.com/search.md#query-fields-for-invoices) - [Abfragefelder für PaymentIntents](https://docs.stripe.com/search.md#query-fields-for-paymentintents) - [Abfragefelder für Preise](https://docs.stripe.com/search.md#query-fields-for-prices) - [Abfragefelder für Produkte](https://docs.stripe.com/search.md#query-fields-for-products) - [Abfragefelder für Abonnements](https://docs.stripe.com/search.md#query-fields-for-subscriptions) ## 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](https://docs.stripe.com/upgrades.md), 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: ```bash -H "Stripe-Version: 2026-04-22.dahlia" ``` Lesen Sie unseren [SDK](https://docs.stripe.com/sdks.md#versioning)-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](https://docs.stripe.com/api/invoices/list.md)). 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](https://docs.stripe.com/api/payment_intents/search.md) 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 einen [Grenzwert](https://docs.stripe.com/rate-limits.md) von bis zu 20 Lesevorgängen pro Sekunde an. Dies gilt für alle Suchen-Endpoints, sowohl im Live-Modus als auch in Testumgebungen. Die Grenzwerte für den Live-Modus und die Testumgebungen sind getrennt. Was die Begrenzung angeht, ist bei Workloads, bei denen Sie Analysen für eine oder mehrere API-Ressourcen ausführen müssen, [Sigma](https://docs.stripe.com/stripe-data/how-sigma-works.md) deutlich effizienter. Bei Workloads, bei denen Sie einen Großteil Ihrer API-Ressource exportieren müssen, ist unser Produkt [Data Pipeline](https://docs.stripe.com/stripe-data/access-data-in-warehouse.md) die bessere Wahl. ### Regionale Verfügbarkeit Die Suche ist für Unternehmen in Indien nicht verfügbar. ### Test-Uhren-Objekte in Liste aller Ergebnisse ausgelassen Stripe-Listen-APIs (wie [Listen-Rechnungen](https://docs.stripe.com/api/invoices/list.md)) 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. ### Paginierung In seltenen Fällen kann das Paginieren über eine Ergebnismenge dazu führen, dass einige Datensätze neu geordnet werden. Dadurch fehlen sie auf einer Seite oder werden dupliziert. Wenn Sie auf dieses Problem stoßen, kontaktieren Sie uns über das Formular unter [Stripe-Support](https://support.stripe.com). ## Beispiele Hier sind einige Beispiele dafür, was Sie mit der [Search Charges API](https://docs.stripe.com/api/charges/search.md) und der [Search PaymentIntents API](https://docs.stripe.com/api/payment_intents/search.md) tun können: ### Suche nach Zahlungen anhand der Metadaten Suchen Sie nach Zahlungen basierend auf einem übereinstimmenden nutzerdefinierten Metadatenwert. ```curl curl -G https://api.stripe.com/v1/charges/search \ -u "<>:" \ --data-urlencode "query=metadata['key']:'value'" ``` ### 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. ```curl curl -G https://api.stripe.com/v1/charges/search \ -u "<>:" \ --data-urlencode "query=payment_method_details.card.last4:4242" ``` ### Kundensuche auf Basis der E-Mail-Adresse Suchen Sie nach Kund/innen basierend auf einer übereinstimmenden E-Mail-Adresse. ```curl curl -G https://api.stripe.com/v1/customers/search \ -u "<>:" \ --data-urlencode "query=email:'sally@rocketrides.io'" ``` ### Negationsfilter Suchen Sie nach PaymentIntents, deren Währung nicht USD ist. ```curl curl -G https://api.stripe.com/v1/payment_intents/search \ -u "<>:" \ --data-urlencode "query=-currency:'usd'" ``` ### Numerischer Filter Filtern Sie nach Rechnungsobjekten, deren Wert für `total` größer als 1.000 ist. ```curl curl -G https://api.stripe.com/v1/invoices/search \ -u "<>:" \ -d "query=total>1000" ``` ### Kombination mehrerer Filter Suchen Sie nach Zahlungen basierend auf einer Kombination aus übereinstimmenden Metadaten und Währung. ```curl curl -G https://api.stripe.com/v1/charges/search \ -u "<>:" \ --data-urlencode "query=metadata['key']:'value' AND currency:'usd'" ``` ## 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](https://docs.stripe.com/search.md#supported-query-fields-for-each-resource). 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) | | 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](https://docs.stripe.com/api/metadata.md) 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[""]:""`. 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. | | `>`, `<`, `=` | - `fieldvalue` - `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](https://docs.stripe.com/terminal/payments/additional-payment-methods.md). 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 terminalbezogenen Feldern, die nicht spezifisch für Karten sind, wie beispielsweise `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 |