You can use the Search API to retrieve your Stripe objects in a flexible manner using a custom query language.
Some examples of what you can do with the Search API:
- Look up charges based on their metadata values.
- Look up charges based on the last 4 digits of their card number.
- Look up customers based on their email.
- Use a negation to find Payment Intents that are not in the USD currency.
- Use greater than and less than filters on certain numeric fields such as
- Combine multiple filters using a logical
Request an invite
Sharing feedback and feature requests
We’re excited to hear your feedback and ideas to make the Search API better. Please send an email to email@example.com to share your thoughts.
Using the API
The Search API is currently invite only and is not fully supported in all of Stripe’s official client libraries. We do have native support via beta packages for Java and Node.js. We will support the Search API beta packages during the beta period (up to March 31, 2022). To use the Search API beta package, add it to your package manifest as a replacement for the standard Stripe library:
After that, a
search method is available on each of the searchable resources:
Please use the following versions of the beta packages:
Beta Package Name
Without a beta package
To use the search API outside of a beta package, specify the version of the beta inside the
Stripe-Version request header:
-H "Stripe-Version: 2020-08-27;search_api_beta=v1"
The official Stripe client libraries do not natively support the beta release of the Search API. However, in Ruby, Python, and PHP, you can still use the Stripe library to manually make Search API requests.
Charges metadata search
Look up charges based on a custom metadata value.
Charges last4 search
Look up charges based on the last 4 digits of the card used for the payment.
Customers email search
Look up customers based on their email.
Use a negation filter
Look up PaymentIntents which are not in the USD currency.
Filter invoice objects with an
total greater than 1000.
Combining multiple filters
Look up charges based on a combination of metadata and currency.
Change the search window
By default, the Search API searches across data created in the past year. To search across available historical data, pass the URL parameter
search_window. This example shows searching for charges with
currency:"USD" created over
Search query language
Query structure and terminology
A query clause consists of a field followed by an operator followed by a value:
You can combine multiple query clauses in a search by either separating them with a space, or using the AND or OR keywords (case insensitive). By default, clauses are combined with AND logic. AND and OR are mutually exclusive.
The following example search
email:"firstname.lastname@example.org" metadata["key"]:"value" demonstrates how to create a clause that matches records where both email address is email@example.com and metadata in the record includes “key” with a value of “value”.
Creating a query which does not match a clause
You can negate query clauses using a
- character. For example, the following search returns records that do not match the email
Field types, substring matching, and numeric comparators
Every search field supports exact matching with a
:. Certain fields such as
name support substring matching. Certain other fields such as
amount support numeric comparators like
Each field includes a type that defines the operations you can use on the field. To see a full list of available fields and types, see API Details.
Using an unsupported operator, such as specifying greater than (>) on a string, returns an error.
|token||exact match (case insensitive)|
|string||exact match, substring (case insensitive)|
|numeric||exact match, greater than and less than|
You must use quotation marks around string values. Quotation marks are optional for numeric values. For example:
currency:"USD"→ Quotes required
last4:1234→ Quotes optional
You can escape quotes inside of quotes with a backslash (
description:"the story called \"The Sky and the Sea.\""
Metadata fields are given special treatment, because both the field and value are user-provided and can be an arbitrary string.
Use the following format to construct a clause for a metadata search:
The following clause demonstrates how to create a clause that queries for records with a donation ID of “asdf-jkl”:
The following table lists the syntax that you can use to construct a query.
|Exact match operator|
|The query returns only records that match both clauses (case insensitive)|
|The query returns records that match either of the clauses (case insensitive)|
|Returns records that do not match the clause|
|A special token used for field presence (case insensitive)|
|Escape quotes within quotes|
|Substring match operator|
|Greater than/less than operators|
Don’t use search for read-after-write flows (e.g. searching immediately after a charge is made) as the data won’t be immediately available to search. Under normal operating conditions data is searchable in minutes. Occasionally, propagation of new or updated data can be up to an hour behind during outages.
We apply general Stripe rate limits for read operations to this endpoint as documented here: Rate limits.