Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
Security
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Quickstart
Stripe Shell
Stripe CLI
Dashboard
Stripe for Visual Studio Code
Webhooks
File uploads
Error handling
API
Tour
Keys
Libraries
Upgrades
Rate limits
Card testing
Expanding responses
Domains and IP addresses
Search
Building With Stripe
React Stripe.js
Prebuilt iOS UI
Prebuilt Android UI
Extensions
Connectors
Samples
Checklist
Feedback
HomeDeveloper tools

Search

Look up objects in your Stripe data.

Overview

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 get started, visit the API reference for a searchable resource.

  • Search for charges
  • Search for customers
  • Search for invoices
  • Search for PaymentIntents
  • Search for prices
  • Search for products
  • Search for subscriptions

Examples

Some examples of what you can do with the Search API:

Charges metadata search

Look up charges matching a custom metadata value.

curl https://api.stripe.com/v1/charges/search \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d query="metadata['key']:'value'" \ -G

Charges last4 search

Look up charges matching the last 4 digits of the card used for the payment.

curl https://api.stripe.com/v1/charges/search \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d query="payment_method_details.card.last4:4242" \ -G

Customers email search

Look up customers matching an email.

curl https://api.stripe.com/v1/customers/search \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d query="email:'sally@rocketrides.io'" \ -G

Negation filter

Look up PaymentIntents not in the USD currency.

curl https://api.stripe.com/v1/payment_intents/search \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d query="-currency:'usd'" \ -G

Numeric filter

Filter invoice objects with a total greater than 1000.

curl https://api.stripe.com/v1/invoices/search \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d query="total>1000" \ -G

Combining multiple filters

Look up charges matching a combination of metadata and currency.

curl https://api.stripe.com/v1/charges/search \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d query="metadata['key']:'value' AND currency:'USD'" \ -G

Search query language

Query structure and terminology

A query clause consists of a field followed by an operator followed by a value:

clauseemail:"amy@rocketrides.io"
fieldemail
operator:
valueamy@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, clauses are combined with AND logic. AND and OR 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
tokenexact 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 name:"one two three" would match both a result with the name “one two three” and a result with the name “one two three four”.

numericexact 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:1234 means 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:valueExact match operator (case insensitive)currency:"EUR" returns records where the currency is exactly “EUR” in a case-insensitive comparison
AND, andfield:value1 AND field:value2The query returns only records that match both clauses (case insensitive)status:"active" AND amount:500
OR, orfield:value1 OR field:value2The query returns records that match either of the clauses (case insensitive)currency:"usd" OR currency:"eur"
--field:valueReturns records that don’t match the clause-currency:"JPY" returns records that aren’t in JPY
NULL, nullfield:nullA special token used for field presence (case insensitive)url:null returns records where a url field is empty
\" \"\""Escape quotes within quotesdescription:"the story called \"The Sky and the Sea.\""
~field~valueSubstring match operatoremail~"amy" returns matches for amy@rocketrides.io and xamy
>, <, =
  • field<value
  • field>value
  • field>=value
  • field<=value
Greater than/less than operatorsamount>="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)
amountamount>1000numeric
billing_details.address.postal_codebilling_details.address.postal_code:12345token
createdcreated>1620310503numeric
currencycurrency:"usd"token
customercustomer:"cus_123"token
metadatametadata["key"]:"value"token
payment_method_details.card.last4payment_method_details.card.last4:1234token
payment_method_details.card.exp_monthpayment_method_details.card.exp_month:12token
payment_method_details.card.exp_yearpayment_method_details.card.exp_year:2022token
payment_method_details.card.brandpayment_method_details.card.brand:"visa"token
payment_method_details.card.fingerprintpayment_method_details.card.fingerprint:"fp"token
statusstatus:"succeeded"token

Query fields for customers

Field
usage
Type (token, string, numeric)
createdcreated>1620310503numeric
emailemail~"amyt"string
metadatametadata["key"]:"value"token
namename~"amy"string
phonephone:"+19999999999"string

Query fields for invoices

Field
usage
Type (token, string, numeric)
createdcreated>1620310503numeric
currencycurrency:"usd"token
customercustomer:"cus_123"token
metadatametadata["key"]:"value"token
numbernumber:"MYSHOP-123"string
receipt_numberreceipt_number:"RECEIPT-123"string
subscriptionsubscription:"SUBS-123"string
totaltotal>1000numeric

Query fields for payment intents

Field
usage
Type (token, string, numeric)
amountamount>1000numeric
createdcreated>1620310503numeric
currencycurrency:"usd"token
customercustomer:"cus_123"token
metadatametadata["key"]:"value"token
statusstatus:"succeeded"token

Query fields for prices

Field
usage
Type (token, string, numeric)
activeactive:"true"token
currencycurrency:"usd"token
lookup_keylookup_key:"standard_monthly"string
metadatametadata["key"]:"value"token
productproduct:"prod_123"string
typetype:"recurring"token

Query fields for products

Field
usage
Type (token, string, numeric)
activeactive:"true"token
descriptiondescription~"t-shirts"string
metadatametadata["key"]:"value"token
namename~"amy"string
shippableshippable:"true"token
urlurl~"/dinosaur_swag"string

Query fields for subscriptions

Field
usage
Type (token, string, numeric)
createdcreated>1620310503numeric
metadatametadata["key"]:"value"token
statusstatus:"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:

Terminal
-H "Stripe-Version: 2020-08-27"

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.

Was this page helpful?
Questions? Contact us.
View developer tutorials on YouTube.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Overview
Examples
Search query language
Supported query fields for each resource
Limitations
Stripe Shell
Test mode
▗▄ ▄▟█ █▀▀ ▗▟████▙▖ ██████ ███▗▟█ ███ ███▗▟██▙▖ ▗▟█████▙▖ ███▖ ▀▀ ███ ███▀▀▀ ███ ███▀ ███ ███ ███ ▝▜████▙▖ ███ ███ ███ ███ ███ █████████ ▄▄ ▝███ ███ ▄ ███ ███ ███▄ ███ ███ ▄▄ ▝▜████▛▘ ▝▜███▛ ███ ███ ███▝▜██▛▘ ▝▜█████▛▘ ███ ▀▘
Welcome to the Stripe Shell! This is a graphical user interface of the Stripe CLI. You can use it to discover webhook events and manage your Stripe resources. By pressing ctrl + ` you can toggle it open from any page within the Stripe documentation. - View supported commands: - Listen for webhook events: - Trigger webhook events: - Call Stripe APIs: stripe [api resource] [api operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$