Many objects allow you to request additional information as an expanded response by using the expand
request parameter. This parameter is available on all API requests, and applies to the response of that request only. You can expand responses in two ways.
In many cases, an object contains the ID of a related object in its response properties. For example, a Charge
might have an associated Customer ID. You can expand these objects in line with the expand request parameter. The expandable
label in this documentation indicates ID fields that you can expand into objects.
Some available fields arenât included in the responses by default, such as the number
and cvc
fields for the Issuing Card object. You can request these fields as an expanded response by using the expand
request parameter.
You can expand recursively by specifying nested fields after a dot (.
). For example, requesting invoice.
on a charge expands the invoice
property into a full Invoice object, then expands the subscription
property on that invoice into a full Subscription object.
You can use the expand
parameter on any endpoint that returns expandable fields, including list, create, and update endpoints.
Expansions on list requests start with the data
property. For example, you can expand data.
on a request to list charges and associated customers. Performing deep expansions on numerous list requests might result in slower processing times.
Expansions have a maximum depth of four levels (for example, the deepest expansion allowed when listing charges is data.
).
You can expand multiple objects at the same time by identifying multiple items in the expand
array.
- Related guide: Expanding responses
- Related video: Expand
{ "id": "ch_3LmzzQ2eZvKYlo2C0XjzUzJV", "object": "charge", "customer": { "id": "cu_14HOpH2eZvKYlo2CxXIM7Pb2", "object": "customer", // ... }, "invoice": { "id": "in_1LmzzQ2eZvKYlo2CpyWn8szu", "object": "invoice", "subscription": { "id": "su_1LmzoG2eZvKYlo2Cpw6S7dAq", "object": "subscription", // ... }, // ... }, // ...}
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice.
To perform an idempotent request, provide an additional IdempotencyKey
element to the request options.
Stripeâs idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeds or fails. Subsequent requests with the same key return the same result, including 500
errors.
A client generates an idempotency key, which is a unique key that the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys are up to 255 characters long.
You can remove keys from the system automatically after theyâre at least 24 hours old. We generate a new request if a key is reused after the original is pruned. The idempotency layer compares incoming parameters to those of the original request and errors if theyâre the same to prevent accidental misuse.
We save results only after the execution of an endpoint begins. If incoming parameters fail validation, or the request conflicts with another request thatâs executing concurrently, we donât save the idempotent result because no API endpoint initiates the execution. You can retry these requests. Learn more about when you can retry idempotent requests.
All POST
requests accept idempotency keys. Donât send idempotency keys in GET
and DELETE
requests because it has no effect. These requests are idempotent by definition.
Updateable Stripe objectsâincluding Account, Charge, Customer, PaymentIntent, Refund, Subscription, and Transfer have a metadata
parameter. You can use this parameter to attach key-value data to these Stripe objects.
You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.
You can use metadata to store additional, structured information on an object. For example, you could store your userâs full name and corresponding unique identifier from your system on a Stripe Customer object. Stripe doesnât use metadataâfor example, we donât use it to authorize or decline a charge and it wonât be seen by your users unless you choose to show it to them.
Some of the objects listed above also support a description
parameter. You can use the description
parameter to annotate a charge-for example, a human-readable description such as 2 shirts for test@example.
. Unlike metadata
, description
is a single string, which your users might see (for example, in email receipts Stripe sends on your behalf).
Donât store any sensitive information (bank account numbers, card details, and so on) as metadata or in the description
parameter.
- Related guide: Metadata
Sample metadata use cases
- Link IDs: Attach your systemâs unique IDs to a Stripe object to simplify lookups. For example, add your order number to a charge, your user ID to a customer or recipient, or a unique receipt number to a transfer.
- Refund papertrails: Store information about the reason for a refund and the individual responsible for its creation.
- Customer details: Annotate a customer by storing an internal ID for your future use.
{ "id": "cus_123456789", "object": "customer", "address": { "city": "city", "country": "US", "line1": "line 1", "line2": "line 2", "postal_code": "90210", "state": "CA" }, "balance": 0, "created": 1483565364, "currency": null, "default_source": null, "delinquent": false, "description": null, "discount": null, "email": null, "invoice_prefix": "C11F7E1", "invoice_settings": { "custom_fields": null, "default_payment_method": null, "footer": null, "rendering_options": null }, "livemode": false, "metadata": { "order_id": "6735" }, "name": null, "next_invoice_sequence": 1, "phone": null, "preferred_locales": [], "shipping": null, "tax_exempt": "none"}
All top-level API resources have support for bulk fetches through âlistâ API methods. For example, you can list charges, list customers, and list invoices. These list API methods share a common structure and accept, at a minimum, the following three parameters: limit
, starting_
, and ending_
.
Stripeâs list API methods use cursor-based pagination through the starting_
and ending_
parameters. Both parameters accept an existing object ID value (see below) and return objects in reverse chronological order. The ending_
parameter returns objects listed before the named object. The starting_
parameter returns objects listed after the named object. These parameters are mutually exclusive. You can use either the starting_
or ending_
parameter, but not both simultaneously.
Our client libraries offer auto-pagination helpers to traverse all pages of a list.
Parameters
- limitoptional, default is 10
This specifies a limit on the number of objects to return, ranging between 1 and 100.
- starting_
afteroptional object ID A cursor to use in pagination.
starting_
is an object ID that defines your place in the list. For example, if you make a list request and receive 100 objects, ending withafter obj_
, your subsequent call can includefoo starting_
to fetch the next page of the list.after=obj_ foo - ending_
beforeoptional object ID A cursor to use in pagination.
ending_
is an object ID that defines your place in the list. For example, if you make a list request and receive 100 objects, starting withbefore obj_
, your subsequent call can includebar ending_
to fetch the previous page of the list.before=obj_ bar
List Response Format
- objectstring, value is "list"
A string that provides a description of the object type that returns.
- dataarray
An array containing the actual response elements, paginated by any request parameters.
- has_
moreboolean Whether or not there are more elements available after this set. If
false
, this set comprises the end of the list. - urlurl
The URL for accessing this list.
{ "object": "list", "url": "/v1/customers", "has_more": false, "data": [ { "id": "cus_4QFJOjw2pOmAGJ", "object": "customer", "address": null, "balance": 0, "created": 1405641735, "currency": "usd", "default_source": "card_14HOpG2eZvKYlo2Cz4u5AJG5", "delinquent": false, "description": "New customer", "discount": null, "email": null, "invoice_prefix": "7D11B54", "invoice_settings": { "custom_fields": null, "default_payment_method": null, "footer": null, "rendering_options": null }, "livemode": false, "metadata": { "order_id": "6735" }, "name": "cus_4QFJOjw2pOmAGJ", "next_invoice_sequence": 25, "phone": null, "preferred_locales": [], "shipping": null, "tax_exempt": "none", "test_clock": null }, ]}
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_
response parameter. For example, if you make a search request and receive "next_
in the response, your subsequent call can include page=pagination_
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_
value returned in a previous response to request subsequent results.page
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_
is true, you can pass the value ofmore next_
to a subsequent call to fetch the next page of results.page - 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_
field.count
{ "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, "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 } ]}