Many objects allow you to request additional information as an expanded response by using theexpand 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, aCharge might have an associated Customer ID. You can expand these objects in line with the expand request parameter. Theexpandable 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 thenumber andcvc fields for the Issuing Card object. You can request these fields as an expanded response by using theexpand request parameter.

You can expand recursively by specifying nested fields after a dot (.). For example, requestingpayment_intent.customer on a charge expands thepayment_intent property into a full PaymentIntent object, then expands thecustomer property on that payment intent into a full Customer object.

You can use theexpand parameter on any endpoint that returns expandable fields, including list, create, and update endpoints.

Expansions on list requests start with thedata property. For example, you can expanddata.customers 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 isdata.payment_intent.customer.default_source).

You can expand multiple objects at the same time by identifying multiple items in theexpand array.

• Related guide:Expanding responses
• Related video:Expand

The API supportsidempotency 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 additionalIdempotencyKey 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, including500 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 not 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 canretry idempotent requests.

AllPOST requests accept idempotency keys. Don’t send idempotency keys inGET andDELETE requests because it has no effect. These requests are idempotent by definition.

Some API v2 responses contain null values for certain properties by default, regardless of their actual values. That reduces the size of response payloads while maintaining the basic response structure. To retrieve the actual values for those properties, specify them in theinclude array request parameter.

To determine whether you need to use theinclude parameter in a given request, look at the request description. Theinclude parameter’s enum values represent the response properties that depend on theinclude parameter.

A hash property can depend on a singleinclude value, or on multipleinclude values associated with its child properties. For example, when updating an Account, to return actual values for the entireidentity hash, specifyidentity in theinclude parameter. Otherwise, theidentity hash is null in the response. However, to return actual values for theconfiguration hash, you must specify individual configurations in the request. If you specify at least one configuration, but not all of them, specified configurations return actual values and unspecified configurations return null. If you don’t specify any configurations, theconfiguration hash is null in the response.

• Related guide:Include-dependent response values

Updateable Stripe objects—includingAccount,Charge,Customer,PaymentIntent,Refund,Subscription, andTransfer have ametadata 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. Keys and values are stored as strings and can contain any characters with one exception: you can’t use square brackets ([ and ]) in keys.

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 StripeCustomer 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 adescription parameter. You can use thedescription parameter to annotate a charge-for example, a human-readable description such as2 shirts for test@example.com. Unlikemetadata,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 thedescription 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.

All top-level API resources have support for bulk fetches through “list” API methods. For example, you canlist charges,list customers, andlist invoices. These list API methods share a common structure and accept, at a minimum, the following three parameters:limit,starting_after, andending_before.

Stripe’s list API methods use cursor-basedpagination through thestarting_after andending_before parameters. Both parameters accept an existing object ID value (see below) and return objects in reverse chronological order. Theending_before parameter returns objects listed before the named object. Thestarting_after parameter returns objects listed after the named object. These parameters are mutually exclusive. You can use either thestarting_after orending_before parameter, but not both simultaneously.

Our client libraries offerauto-pagination helpers to traverse all pages of a list.