Search

Some top-level API resource have support for retrieval via “search” API methods. For example, you can search charges, search customers, and search subscriptions.

Stripe’s search API methods utilize cursor-based pagination via the page request parameter and next_page response parameter. For example, if you make a search request and receive "next_page": "pagination_key" in the response, your subsequent call can include page=pagination_key to fetch the next page of results.

Our client libraries offer auto-pagination helpers to easily traverse all pages of a search result.

Search request format

queryrequired
The search query string. See search query language.

limitoptional
A limit on the number of objects returned. Limit can range between 1 and 100, and the default is 10.

pageoptional
A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Search response format

objectstring, value is "search_result"
A string describing the object type returned.

urlstring
The URL for accessing this list.

has_moreboolean
Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

dataarray
An array containing the actual response elements, paginated by any request parameters.

next_pagestring
A cursor for use in pagination. If has_more is true, you can pass the value of next_page to a subsequent call to fetch the next page of results.

total_countoptional positive integer or zero
The total number of objects that match the query, only accurate up to 10,000. This field isn’t included by default. To include it in the response, expand the total_count field.

Response

{
  "object": "search_result",
  "url": "/v1/customers/search",
  "has_more": false,
  "data": [
    {
      "id": "cus_4QFJOjw2pOmAGJ",
      "object": "customer",
      "address": null,
      "balance": 0,
      "created": 1405641735,
      "currency": "usd",
      "default_source": "card_14HOpG2eZvKYlo2Cz4u5AJG5",
      "delinquent": false,
      "description": "someone@example.com for Coderwall",
      "discount": null,
      "email": null,
      "invoice_prefix": "7D11B54",
      "invoice_settings": {
        "custom_fields": null,
        "default_payment_method": null,
        "footer": null,
        "rendering_options": null
      },
      "livemode": false,
      "metadata": {
        "foo": "bar"
      },
      "name": "fakename",
      "next_invoice_sequence": 25,
      "phone": null,
      "preferred_locales": [],
      "shipping": null,
      "tax_exempt": "none",
      "test_clock": null
    }
  ]
}

Auto-pagination

Our libraries support auto-pagination. This feature allows you to easily iterate through large lists of resources without having to manually perform the requests to fetch subsequent pages.

To use the auto-pagination feature in Ruby, simply issue an initial “list” call with the parameters you need, then call auto_paging_each on the returned list object to iterate over all objects matching your initial parameters.

Server-side language

require 'stripe'
Stripe.api_key = 'sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2'
customers = Stripe::Customer.list({limit: 3})
customers.auto_paging_each do |customer|
  # Do something with customer
end

Request IDs

Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. You can also find request identifiers in the URLs of individual request logs in your Dashboard.

To expedite the resolution process, provide the request identifier when you contact us about a specific request.

Server-side language

require 'stripe'
Stripe.api_key = 'sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2'
client = Stripe::StripeClient.new()
customer, response = client.request do
  Stripe::Customer.create()
end
puts response.request_id

Versioning

Each major release, such as Acacia, includes changes that aren’t backward-compatible with previous releases. Upgrading to a new major release can require updates to existing code. Each monthly release includes only backward-compatible changes, and uses the same name as the last major release. You can safely upgrade to a new monthly release without breaking any existing code. The current version is 2025-08-27.basil. For information on all API versions, view our API changelog.

Starting from stripe-ruby v9, the requests you send using stripe-ruby align with the API version that was current when your version of stripe-ruby was released.
On stripe-ruby v8 or lower, requests made with stripe-ruby use your Stripe account’s default API version, controlled in Workbench.

You can override the API version in your code in all versions.

To override the API version, assign the version to the Stripe.api_version property, or set it per-request. When overriding it per-request, methods on the returned object reuse the same Stripe version.

Webhook events use the API version that’s set during your webhook’s endpoint creation. Otherwise, they use your Stripe account’s default API version (controlled in Workbench). If you’re on stripe-ruby v9 or later, match your webhook endpoint API version to the version pinned by your stripe-ruby version (Stripe.api_version property).

You can upgrade your API version in Workbench. As a precaution, use API versioning to test a new API version before committing to an upgrade.

Server-side language

require 'stripe'
Stripe.api_key = 'sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2'
Stripe.api_version = '2025-08-27.basil'

Balance

This is an object representing your Stripe balance. You can retrieve it to see the balance currently on your Stripe account.

The top-level available and pending comprise your “payments balance.”

Endpoints

GET/v1/balance

Search

Search request format

queryrequired

limitoptional

pageoptional

Search response format

objectstring, value is "search_result"

urlstring

has_moreboolean

dataarray

next_pagestring

total_countoptional positive integer or zero

Auto-pagination

Request IDs

Versioning

Balance