[metadata]
viewport: width=device-width, initial-scale=1.0, viewport-fit=cover

[document-links]
/api
Account Links v2: https://docs.stripe.com/api/v2/core/account-links
Account Links: https://docs.stripe.com/api/account_links
Account Sessions: https://docs.stripe.com/api/account_sessions
Account Tokens v2: https://docs.stripe.com/api/v2/core/account-tokens
Account: /api/accounts
Accounts v2: https://docs.stripe.com/api/v2/core/accounts
Accounts: https://docs.stripe.com/api/accounts
Alerts: https://docs.stripe.com/api/billing/alert
Application Fee Refunds: https://docs.stripe.com/api/fee_refunds
Application Fees: https://docs.stripe.com/api/application_fees
Authentication: https://docs.stripe.com/api/authentication
Balance Settings: https://docs.stripe.com/api/balance-settings
Balance Transactions: https://docs.stripe.com/api/balance_transactions
Balances: https://docs.stripe.com/api/balance
Bank Accounts: https://docs.stripe.com/api/customer_bank_accounts
Capabilities: https://docs.stripe.com/api/capabilities
Cards: https://docs.stripe.com/api/cards
Cash Balance Transactions: https://docs.stripe.com/api/cash_balance_transactions
Cash Balances: https://docs.stripe.com/api/cash_balance
Charge: /api/charges
Charges: https://docs.stripe.com/api/charges
Checkout Sessions: https://docs.stripe.com/api/checkout/sessions
Confirmation Tokens: https://docs.stripe.com/api/confirmation_tokens
Connected Accounts: https://docs.stripe.com/api/connected-accounts
Contact Sales: https://stripe.com/contact/sales
Contact Support: https://support.stripe.com/
Country Specs: https://docs.stripe.com/api/country_specs
Coupons: https://docs.stripe.com/api/coupons
Credit Balance Summaries: https://docs.stripe.com/api/billing/credit-balance-summary
Credit Balance Transactions: https://docs.stripe.com/api/billing/credit-balance-transaction
Credit Grants: https://docs.stripe.com/api/billing/credit-grant
Credit Notes: https://docs.stripe.com/api/credit_notes
Customer Balance Transactions: https://docs.stripe.com/api/customer_balance_transactions
Customer Portal Configurations: https://docs.stripe.com/api/customer_portal/configurations
Customer Portal Sessions: https://docs.stripe.com/api/customer_portal/sessions
Customer Sessions: https://docs.stripe.com/api/customer_sessions
Customer: /api/customers
Customers: https://docs.stripe.com/api/customers
Discord: https://stripe.com/go/developer-chat
Discounts: https://docs.stripe.com/api/discounts
Disputes: https://docs.stripe.com/api/disputes
Docs: /
Errors: https://docs.stripe.com/api/errors
Event Destinations v2: https://docs.stripe.com/api/v2/core/event-destinations
Events v2: https://docs.stripe.com/api/v2/core/events
Events: https://docs.stripe.com/api/events
Expanding Responses: https://docs.stripe.com/api/expanding_objects
External Account Cards: https://docs.stripe.com/api/external_account_cards
External Bank Accounts: https://docs.stripe.com/api/external_accounts
File Links: https://docs.stripe.com/api/file_links
Files: https://docs.stripe.com/api/files
Financing Offers: https://docs.stripe.com/api/capital/financing_offers
Financing Summaries: https://docs.stripe.com/api/capital/financing_summary
Idempotent requests: /api/idempotent_requests
Idempotent requests: https://docs.stripe.com/api/idempotent_requests
Include-dependent response values (API v2): /api/include_dependent_response_values
Include-dependent response values (API v2): https://docs.stripe.com/api/include_dependent_response_values
Include-dependent response values: /api-includable-response-values
Introduction: https://docs.stripe.com/api
Invoice Items: https://docs.stripe.com/api/invoiceitems
Invoice Line Items: https://docs.stripe.com/api/invoice-line-item
Invoice Payments: https://docs.stripe.com/api/invoice-payment
Invoice Rendering Templates: https://docs.stripe.com/api/invoice-rendering-template
Invoices: https://docs.stripe.com/api/invoices
Login Links: https://docs.stripe.com/api/accounts/login_link
Mandates: https://docs.stripe.com/api/mandates
Markdoc: https://markdoc.dev
Metadata: /api/metadata
Metadata: /metadata
Metadata: https://docs.stripe.com/api/metadata
Meter Event Adjustment: https://docs.stripe.com/api/billing/meter-event-adjustment
Meter Event Adjustments v2: https://docs.stripe.com/api/v2/billing/meter-event-adjustments
Meter Event Streams v2: https://docs.stripe.com/api/v2/meter-event-streams
Meter Event Summary: https://docs.stripe.com/api/billing/meter-event-summary
Meter Events v2: https://docs.stripe.com/api/v2/meter-events
Meter Events: https://docs.stripe.com/api/billing/meter-event
Meters: https://docs.stripe.com/api/billing/meter
Pagination: https://docs.stripe.com/api/pagination
Payment Intents: https://docs.stripe.com/api/payment_intents
Payment Links: https://docs.stripe.com/api/payment-link
Payment Method Configurations: https://docs.stripe.com/api/payment_method_configurations
Payment Method Domains: https://docs.stripe.com/api/payment_method_domains
Payment Methods: https://docs.stripe.com/api/payment_methods
PaymentIntent: /api/payment_intents
Payouts: https://docs.stripe.com/api/payouts
Person Tokens v2: https://docs.stripe.com/api/v2/core/person-tokens
Persons v2: https://docs.stripe.com/api/v2/core/persons
Persons: https://docs.stripe.com/api/persons
Plans: https://docs.stripe.com/api/plans
Prices: https://docs.stripe.com/api/prices
Products: https://docs.stripe.com/api/products
Promotion Codes: https://docs.stripe.com/api/promotion_codes
Quotes: https://docs.stripe.com/api/quotes
Read llms.txt: /llms.txt
Refund: /api/refunds
Refunds: https://docs.stripe.com/api/refunds
Request IDs: https://docs.stripe.com/api/request_ids
Secrets: https://docs.stripe.com/api/secret_management
Setup Attempts: https://docs.stripe.com/api/setup_attempts
Setup Intents: https://docs.stripe.com/api/setup_intents
Shared Payment Granted Tokens: https://docs.stripe.com/api/shared-payment/granted-token
Shared Payment Issued Tokens: https://docs.stripe.com/api/shared-payment/issued-token
Shipping Rates: https://docs.stripe.com/api/shipping_rates
Sign in →: https://dashboard.stripe.com/login?redirect=https%3A%2F%2Fdocs.stripe.com%2Fapi%2Fidempotent_requests
Sources: https://docs.stripe.com/api/sources
Stripe Balance Debit Agreements: https://docs.stripe.com/api/stripe_balance_debit_agreements
Subscription Items: https://docs.stripe.com/api/subscription_items
Subscription Schedules: https://docs.stripe.com/api/subscription_schedules
Subscription: /api/subscriptions
Subscriptions: https://docs.stripe.com/api/subscriptions
Support: https://support.stripe.com
Tax Codes: https://docs.stripe.com/api/tax_codes
Tax IDs: https://docs.stripe.com/api/tax_ids
Tax Rates: https://docs.stripe.com/api/tax_rates
Test Clocks: https://docs.stripe.com/api/test_clocks
Tokens: https://docs.stripe.com/api/tokens
Top-ups: https://docs.stripe.com/api/topups
Transfer Reversals: https://docs.stripe.com/api/transfer_reversals
Transfer: /api/transfers
Transfers: https://docs.stripe.com/api/transfers
Versioning: https://docs.stripe.com/api/versioning
changelog: /changelog
idempotency: https://en.wikipedia.org/wiki/Idempotence
retry idempotent requests: /error-low-level#idempotency

[content]
Idempotent requests | Stripe API Reference
Find anything
/
Ask AI
Introduction
Authentication
Errors
Expanding Responses
Idempotent requests
Include-dependent response values (API v2)
Metadata
Pagination
Request IDs
Connected Accounts
Versioning
Core Resources
Accounts
v2
Account Links
v2
Account Tokens
v2
Balances
Balance Transactions
Charges
Customers
Customer Sessions
Disputes
Events
Events
v2
Event Destinations
v2
Files
File Links
Mandates
Payment Intents
Persons
v2
Person Tokens
v2
Setup Intents
Setup Attempts
Stripe Balance Debit Agreements
Payouts
Refunds
Confirmation Tokens
Tokens
Payment Methods
Payment Methods
Payment Method Configurations
Payment Method Domains
Bank Accounts
Cash Balances
Cash Balance Transactions
Cards
Sources
Products
Products
Prices
Coupons
Promotion Codes
Discounts
Tax Codes
Tax Rates
Shipping Rates
Commerce
Agentic Commerce
Shared Payment Issued Tokens
Shared Payment Granted Tokens
Checkout
Checkout Sessions
Payment Links
Payment Links
Billing
Alerts
Credit Balance Summaries
Credit Balance Transactions
Credit Grants
Credit Notes
Customer Balance Transactions
Customer Portal Configurations
Customer Portal Sessions
Invoices
Invoice Items
Invoice Line Items
Invoice Payments
Invoice Rendering Templates
Meters
Meter Events
Meter Event Adjustment
Meter Event Adjustments
v2
Meter Event Streams
v2
Meter Event Summary
Meter Events
v2
Plans
Quotes
Subscriptions
Subscription Items
Subscription Schedules
Tax IDs
Test Clocks
Capital
Financing Offers
Financing Summaries
Connect
Accounts
Login Links
Account Links
Account Sessions
Application Fees
Application Fee Refunds
Capabilities
Country Specs
Balance Settings
External Bank Accounts
External Account Cards
Persons
Top-ups
Transfers
Transfer Reversals
Secrets
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks
2026-07-29
.
dahlia
API Reference
Docs
Support
Sign in
→
Idempotent requests
Ask about this section
Copy for LLM
View as Markdown
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. Avoid using sensitive data (for example, email addresses or personal identifiers) as idempotency keys.
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 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.
Was this section helpful?
Yes
No
curl
https://api.stripe.com/v1/customers \
-u
sk_test_wsFx86X...E4dMskBgJYrt
sk_test_wsFx86XDJWwmE4dMskBgJYrt
: \
-H
"
Idempotency-Key: KG5LxwFBepaKHyUD
"
\
-d description=
"
My First Test Customer (created for API docs at https://docs.stripe.com/api)
"
Include-dependent response values (API v2)
Ask about this section
Copy for LLM
View as Markdown
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 the
include
array request parameter.
To determine whether you need to use the
include
parameter in a given request, look at the request description. The
include
parameter’s enum values represent the response properties that depend on the
include
parameter.
Note
Whether a response property defaults to null depends on the request endpoint, not the object that the endpoint references. If multiple endpoints return data from the same object, a particular property can depend on
include
in one endpoint and return its actual value by default for a different endpoint.
A hash property can depend on a single
include
value, or on multiple
include
values associated with its child properties. For example, when updating an Account, to return actual values for the entire
identity
hash, specify
identity
in the
include
parameter. Otherwise, the
identity
hash is null in the response. However, to return actual values for the
configuration
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, the
configuration
hash is null in the response.
Related
guide
:
Include-dependent response values
curl
-X POST https://api.stripe.com/v2/core/accounts \
-H
"
Authorization: Bearer
sk_test_wsFx86X...E4dMskBgJYrt
sk_test_wsFx86XDJWwmE4dMskBgJYrt
"
\
-H
"
Stripe-Version: 2026-07-29.preview
"
\
--json
'
{
"include": [
"identity",
"configuration.customer"
]
}
'
Included response properties
The response includes actual values for the properties specified in the
include
parameter, and null for all other include-dependent properties.
Response
{
"
id
"
:
"
acct_123
"
,
"
object
"
:
"
v2.core.account
"
,
"
applied_configurations
"
:
[
"
customer
"
,
"
merchant
"
],
"
configuration
"
:
{
"
customer
"
:
{
"
automatic_indirect_tax
"
:
{
...
},
"
billing
"
:
{
...
},
"
capabilities
"
:
{
...
},
...
},
"
merchant
"
:
null
,
"
recipient
"
:
null
},
"
contact_email
"
:
"
furever@example.com
"
,
"
created
"
:
"
2025-06-09T21:16:03.000Z
"
,
"
dashboard
"
:
"
full
"
,
"
defaults
"
:
null
,
"
display_name
"
:
"
Furever
"
,
"
identity
"
:
{
"
business_details
"
:
{
"
doing_business_as
"
:
"
FurEver
"
,
"
id_numbers
"
:
[
{
"
type
"
:
"
us_ein
"
}
],
"
product_description
"
:
"
Saas pet grooming platform at furever.dev using Connect embedded components
"
,
"
structure
"
:
"
sole_proprietorship
"
,
"
url
"
:
"
http://accessible.stripe.com
"
},
"
country
"
:
"
US
"
},
"
livemode
"
:
true
,
"
metadata
"
:
{},
"
requirements
"
:
null
}
Metadata
Ask about this section
Copy for LLM
View as Markdown
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. 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 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
.
com
. 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.
Was this section helpful?
Yes
No
curl
https://api.stripe.com/v1/customers \
-u
"
sk_test_wsFx86X...E4dMskBgJYrt
sk_test_wsFx86XDJWwmE4dMskBgJYrt
:
"
\
-d
"
metadata[order_id]=6735
"
{
"
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
"
}
Need help?
Contact Support
.
Chat with Stripe developers on
Discord
.
Check out our
changelog
.
Questions?
Contact Sales
.
LLM?
Read llms.txt
.
Powered by
Markdoc
