Search
Some top level API resources support retrieval with search API methods. You can use the search APIs to retrieve your Stripe objects in a flexible manner. Using search is a faster alternative to paginating through all resources. To create a search query, review the Search query language and reference the query fields of the resource:
- Query fields for charges
- Query fields for customers
- Query fields for invoices
- Query fields for PaymentIntents
- Query fields for prices
- Query fields for products
- Query fields for subscriptions
Examples
Here are some examples of what you can do with the Search charges API and Search PaymentIntents API:
Charges metadata search
Look up charges matching a custom metadata value.
Charges last4 search
Look up charges matching the last 4 digits of the card used for the payment.
Customers email search
Look up customers matching an email.
Negation filter
Look up PaymentIntents not in the USD currency.
Numeric filter
Filter invoice objects with a total greater than 1000.
Combining multiple filters
Look up charges matching a combination of metadata and currency.
Search query language
Query structure and terminology
A query clause consists of a field followed by an operator followed by a value:
| clause | email:"amy@rocketrides.io" |
| field | email |
| operator | : |
| value | amy@rocketrides.io |
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, the API combines clauses with AND logic. AND and OR operators are mutually exclusive.
The example query email:"amy@rocketrides.io" metadata["key"]:"value" matches records where both the email address is amy@rocketrides.io, and the 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 don’t match the email amy@rocketrides.io.
-email:"amy@rocketrides.io"
Field types, substring matching, and numeric comparators
Every search field supports exact matching with a :. Certain fields such as email and name support substring matching. Certain other fields such as amount support numeric comparators like > and <.
Each field includes a type that defines the operations you can use in the field. For a full list of available fields, see supported query fields for each resource.
Using an unsupported operator, such as specifying greater than (>) on a string, returns an error.
| type | operators |
|---|---|
| token | exact match (case insensitive) |
string | exact match, substring (case insensitive) An exact match on a string type returns any record where that record contains all of the words from the query in the same order. For example the query |
| numeric | exact match, greater than and less than |
Quotes
You must use quotation marks around string values. Quotation marks are optional for numeric values. For example:
currency:"usd"means quotes are required.payment_method_details.card.last4:1234means quotes are optional.
You can escape quotes inside of quotes with a backslash (\).
description:"the story called \"The Sky and the Sea.\""
Metadata
You can perform searches on metadata that you’ve added to objects that support it.
Use the following format to construct a clause for a metadata search: metadata["<field>"]:"<value>".
The following clause demonstrates how to create a clause that queries for records with a donation ID of “asdf-jkl”: metadata["donation-id"]:"asdf-jkl".
You can query for the presence of a metadata key on an object. The following clause would match all records where donation-id is a metadata key. -metadata["donation-id"]:null
Search Syntax
The following table lists the syntax that you can use to construct a query.
| Syntax | Usage | Description | Examples |
|---|---|---|---|
: | field:value | Exact match operator (case insensitive) | currency:"eur" returns records where the currency is exactly “EUR” in a case-insensitive comparison |
AND, and | field:value1 AND field:value2 | The query returns only records that match both clauses (case insensitive) | status:"active" AND amount:500 |
OR, or | field:value1 OR field:value2 | The query returns records that match either of the clauses (case insensitive) | currency:"usd" OR currency:"eur" |
- | -field:value | Returns records that don’t match the clause | -currency:"jpy" returns records that aren’t in JPY |
NULL, null | field:null | A special token used for field presence (case insensitive) | url:null returns records where a url field is empty |
\ | " \"\"" | Escape quotes within quotes | description:"the story called \"The Sky and the Sea.\"" |
~ | field~value | Substring match operator | email~"amy" returns matches for amy@rocketrides.io and xamy |
>, <, = |
| Greater than/less than operators | amount>="10" brings up objects where the amount is 10 or greater |
Supported query fields for each resource
Query fields for charges
| Field | usage | Type (token, string, numeric) |
|---|---|---|
| amount | amount>1000 | numeric |
| billing_details.address.postal_code | billing_details.address.postal_code:12345 | token |
| created | created>1620310503 | numeric |
| currency | currency:"usd" | token |
| customer | customer:"cus_123" | token |
| disputed | disputed:"true" | token |
| metadata | metadata["key"]:"value" | token |
| payment_method_details.card.last4 | payment_method_details.card.last4:1234 | token |
| payment_method_details.card.exp_month | payment_method_details.card.exp_month:12 | token |
| payment_method_details.card.exp_year | payment_method_details.card.exp_year:2022 | token |
| payment_method_details.card.brand | payment_method_details.card.brand:"visa" | token |
| payment_method_details.card.fingerprint | payment_method_details.card.fingerprint:"fp" | token |
| refunded | refunded:"true" | token |
| status | status:"succeeded" | token |
The disputed field accepts only the tokens “true” and “false”, indicating the presence of disputes.
refunded:"true" filters for fully-refunded charges, refunded:"false" filters for partially-refunded charges, and refunded:null filters for non-refunded charges.
Query fields for customers
| Field | usage | Type (token, string, numeric) |
|---|---|---|
| created | created>1620310503 | numeric |
email~"amyt" | string | |
| metadata | metadata["key"]:"value" | token |
| name | name~"amy" | string |
| phone | phone:"+19999999999" | string |
Query fields for invoices
| Field | usage | Type (token, string, numeric) |
|---|---|---|
| created | created>1620310503 | numeric |
| currency | currency:"usd" | token |
| customer | customer:"cus_123" | token |
| metadata | metadata["key"]:"value" | token |
| number | number:"MYSHOP-123" | string |
| receipt_number | receipt_number:"RECEIPT-123" | string |
| subscription | subscription:"SUBS-123" | string |
| total | total>1000 | numeric |
Query fields for payment intents
| Field | usage | Type (token, string, numeric) |
|---|---|---|
| amount | amount>1000 | numeric |
| created | created>1620310503 | numeric |
| currency | currency:"usd" | token |
| customer | customer:"cus_123" | token |
| metadata | metadata["key"]:"value" | token |
| status | status:"succeeded" | token |
Query fields for prices
| Field | usage | Type (token, string, numeric) |
|---|---|---|
| active | active:"true" | token |
| currency | currency:"usd" | token |
| lookup_key | lookup_key:"standard_monthly" | string |
| metadata | metadata["key"]:"value" | token |
| product | product:"prod_123" | string |
| type | type:"recurring" | token |
Query fields for products
| Field | usage | Type (token, string, numeric) |
|---|---|---|
| active | active:"true" | token |
| description | description~"t-shirts" | string |
| metadata | metadata["key"]:"value" | token |
| name | name~"amy" | string |
| shippable | shippable:"true" | token |
| url | url~"/dinosaur_swag" | string |
Query fields for subscriptions
| Field | usage | Type (token, string, numeric) |
|---|---|---|
| created | created>1620310503 | numeric |
| metadata | metadata["key"]:"value" | token |
| status | status:"active" | token |
Limitations
Minimum API version
The minimum supported API Version to use search is 2020-08-27. Read our API upgrades guide to learn more about upgrades. To use search without upgrading your account API version, you can override the API version on a single request by setting the Stripe-Version request header:
-H "Stripe-Version: 2022-11-15"
Read our server-side libraries guide on how to override an API version when using a library.
Data freshness
Don’t use search for read-after-write flows (for example, searching immediately after a charge is made) because the data won’t be immediately available to search. Under normal operating conditions, data is searchable in under 1 minute. Propagation of new or updated data could be more delayed during an outage.
Rate limits
We apply a rate limit of up to 20 read operations per second which applies for all search endpoints in both live mode and test mode. Live mode and test mode limits are separate.
Regional availability
Search isn’t available to merchants in India.