Resources/The Agent API Atlas/Finance/Stripe

Everything an AI agent can do with the Stripe API.

A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.

Endpoints52

API version2026-05-27.dahlia

Last updated22 June 2026

Orientation

How the Stripe API works.

The Stripe API is how an app or AI agent works with a Stripe account: taking a payment, refunding a charge, creating a customer, or running recurring billing through subscriptions and invoices. Access is granted through an API key, and a restricted key carries per-resource permissions that set which resources a call can read or write. Stripe pins a single dated API version per account, and a state change emits an Event that Stripe can deliver to a registered endpoint.

52Endpoints

14Capability groups

27Read

25Write

27Permissions

Authentication

Stripe authenticates first-party calls with a Bearer API key rather than OAuth. A server key is either a full-access secret key (sk_) or a least-privilege restricted key (rk_) that carries per-resource Read or Write permissions; a publishable key (pk_) is the only key safe to use in client code. Connect adds OAuth for connecting third-party Standard accounts. Every key belongs to one mode, either test or live.

Permissions

A restricted key grants each resource None, Read, or Write independently, so a leaked key reaches only what it was scoped to. A 403 response means the key lacks the permission the request needs. Stripe recommends restricted keys over raw secret keys for all new integrations.

Versioning

Stripe pins one dated version per account, like 2026-05-27.dahlia, set in Workbench, and a request can override it with the Stripe-Version header. Named monthly GA releases are backward-compatible, while a '.preview' release introduces breaking changes first. A webhook payload uses the version set on the endpoint that receives it.

Data model

Stripe is resource-oriented REST: form-encoded requests, JSON responses, and predictable /v1/ paths. A payment is modeled as a PaymentIntent, the modern flow, which produces a Charge; recurring billing combines Customers, Products, Prices, Subscriptions, and Invoices. A state change emits an Event object delivered by webhook. Lists are cursor-paginated, and a write is made safe to repeat with the Idempotency-Key header.

Connect & authenticate

Connection & authentication methods.

How an app or AI agent connects to Stripe determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes Stripe tools to agents, and each is governed by the key behind it and the permissions that key carries.

Ways to connect

REST API

The REST API takes form-encoded request bodies, returns JSON, and pages through lists with a cursor, at https://api.stripe.com/v1. A call authenticates with an API key using Bearer or Basic auth. The v2 namespace at https://api.stripe.com/v2 uses JSON bodies and a different pagination model.

Best forConnecting an app or AI agent to Stripe.

Governed byThe key and the permissions it carries.

Docs ↗

Webhooks

Stripe POSTs Event objects to an HTTPS endpoint registered in the Dashboard or via the API. The receiver verifies the Stripe-Signature header against the endpoint's signing secret (whsec_...) to confirm the request came from Stripe. Events are retained for 30 days and can be re-fetched via the Events API.

Best forReceiving Stripe events at an app or AI agent.

Governed byThe signing secret on the endpoint.

Docs ↗

MCP server

A hosted Model Context Protocol server at https://mcp.stripe.com exposes Stripe tools to AI agents and LLM clients. It authenticates with OAuth for granular consent or with a Bearer restricted API key, and supports the Stripe-Account header for Connect. Tools cover generic api_search, api_details, api_read, and api_write, resource-specific tools for customers, charges, refunds, subscriptions, invoices, products, prices, payment links, disputes, and balance, plus docs search.

Best forConnecting an AI agent to Stripe through MCP.

Governed byThe OAuth grant or the restricted key and the permissions it carries.

Docs ↗

Authentication

Secret API key

A secret key is unrestricted and can call every API and resource. It is sent through HTTP Basic auth, as the username, or as a Bearer token. Stripe now recommends restricted keys over raw secret keys for new integrations. A secret key must never be exposed in client code.

TokenBearer API key (sk_live_... / sk_test_...)

Best forServer-side calls with full account access.

Docs ↗

Restricted API key

A restricted key carries per-resource permissions, set to None, Read, or Write when the key is created in the Dashboard. Stripe recommends it for all integrations so a leaked key reaches only what it was scoped to. It authenticates the same way as a secret key.

TokenBearer API key (rk_live_... / rk_test_...)

Best forLeast-privilege server access scoped to specific resources.

Docs ↗

Publishable API key

A publishable key is safe to embed in client code. It is limited to tokenizing payment details and a few client-safe operations, and cannot read or move money.

TokenPublic key (pk_live_... / pk_test_...)

Best forClient-side and front-end (Stripe.js, mobile SDKs).

Docs ↗

Connect (OAuth)

Connect uses the standard OAuth 2.0 authorization-code flow at connect.stripe.com, with a scope of read_only or read_write. The resulting token represents the connected account. A platform can also act on a connected account by sending the Stripe-Account header with its own key.

TokenOAuth access token tied to a connected account (stripe_user_id)

Best forPlatforms connecting to Standard accounts they don't own.

Docs ↗

Capability map

What an AI agent can do in Stripe.

The Stripe API is split into areas an agent can act on, like payments, customers, subscriptions, invoices, and payouts. Each area has its own methods, and writes in some areas move real money or change billing.

Payments (PaymentIntents)

7 endpoints

Methods for working with payments, modeled as PaymentIntents.

A write here changes real payment_intent data.

View endpoints →

Charges

3 endpoints

Methods for working with charges.

A write here changes real charge data.

View endpoints →

Customers

5 endpoints

Methods for working with customers.

A write here changes real customer data.

View endpoints →

Subscriptions

5 endpoints

Methods for working with subscriptions.

A write here changes real subscription data.

View endpoints →

Invoices

5 endpoints

Methods for working with invoices.

A write here changes real invoice data.

View endpoints →

Products

3 endpoints

Methods for working with products.

A write here changes real product data.

View endpoints →

Prices

3 endpoints

Methods for working with prices.

A write here changes real price data.

View endpoints →

Refunds

3 endpoints

Methods for working with refunds.

A write here changes real refund data.

View endpoints →

Payouts

3 endpoints

Methods for working with payouts.

A write here changes real payout data.

View endpoints →

Balance

2 endpoints

Methods for working with the account balance.

A write here changes real balance data.

View endpoints →

Checkout

4 endpoints

Methods for working with Checkout Sessions.

A write here changes real checkout.session data.

View endpoints →

Payment Methods

4 endpoints

Methods for working with payment methods.

A write here changes real payment_method data.

View endpoints →

Events & Webhooks

2 endpoints

Methods for working with events and webhooks.

A write here changes real event data.

View endpoints →

Connect (Accounts)

3 endpoints

Methods for working with Connect accounts.

A write here changes real account data.

View endpoints →

Endpoint reference

Every Stripe API method.

Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.

Hide deprecated

Method	Endpoint	What it does	Access	Permission	Version
Payments (PaymentIntents) Methods for working with payments, modeled as PaymentIntents.7
POST	`/v1/payment_intents`	Create a PaymentIntent to track and orchestrate a payment lifecycle.	write	`PaymentIntents write`	Current
A core write; needs PaymentIntents resource Write on a restricted key. Acts onpayment_intent Permission (capability)`PaymentIntents write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/payment_intents/:id`	Retrieve the details of a PaymentIntent.	read	`PaymentIntents read`	Current
Read-only. Acts onpayment_intent Permission (capability)`PaymentIntents read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/v1/payment_intents/:id`	Update properties of a PaymentIntent (e.g. amount, metadata) before confirmation.	write	`PaymentIntents write`	Current
Limited to 1,000 updates per PaymentIntent per hour. Acts onpayment_intent Permission (capability)`PaymentIntents write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/v1/payment_intents/:id/confirm`	Confirm a PaymentIntent to attempt the payment.	write	`PaymentIntents write`	Current
Triggers the payment attempt and fires payment_intent.succeeded or payment_intent.payment_failed. Acts onpayment_intent Permission (capability)`PaymentIntents write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/v1/payment_intents/:id/capture`	Capture the funds of an existing authorized (uncaptured) PaymentIntent.	write	`PaymentIntents write`	Current
Only for manual-capture PaymentIntents. Acts onpayment_intent Permission (capability)`PaymentIntents write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/v1/payment_intents/:id/cancel`	Cancel a PaymentIntent that is not in a terminal state.	write	`PaymentIntents write`	Current
Releases any held funds. Acts onpayment_intent Permission (capability)`PaymentIntents write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/payment_intents`	List all PaymentIntents (cursor-paginated).	read	`PaymentIntents read`	Current
Read-only. Acts onpayment_intent Permission (capability)`PaymentIntents read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Charges Methods for working with charges.3
POST	`/v1/charges`	Create a charge (legacy direct-charge API; PaymentIntents is preferred).	write	`Charges write`	Current
Legacy; PaymentIntents is preferred for new integrations. Acts oncharge Permission (capability)`Charges write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/charges/:id`	Retrieve the details of a charge.	read	`Charges read`	Current
Read-only. Acts oncharge Permission (capability)`Charges read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/charges`	List all charges (cursor-paginated).	read	`Charges read`	Current
Read-only. Acts oncharge Permission (capability)`Charges read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Customers Methods for working with customers.5
POST	`/v1/customers`	Create a customer object to store payment methods and billing info.	write	`Customers write`	Current
A core write. Acts oncustomer Permission (capability)`Customers write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/customers/:id`	Retrieve a customer.	read	`Customers read`	Current
Read-only. Acts oncustomer Permission (capability)`Customers read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/v1/customers/:id`	Update a customer's properties.	write	`Customers write`	Current
A core write. Acts oncustomer Permission (capability)`Customers write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/customers`	List all customers (cursor-paginated).	read	`Customers read`	Current
Read-only. Acts oncustomer Permission (capability)`Customers read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
DELETE	`/v1/customers/:id`	Permanently delete a customer.	write	`Customers write`	Current
Irreversible; also cancels active subscriptions. Acts oncustomer Permission (capability)`Customers write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Subscriptions Methods for working with subscriptions.5
POST	`/v1/subscriptions`	Create a subscription on a customer for recurring billing.	write	`Subscriptions write`	Current
Limited to 10 new invoices per subscription per minute. Acts onsubscription Permission (capability)`Subscriptions write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/subscriptions/:id`	Retrieve a subscription.	read	`Subscriptions read`	Current
Read-only. Acts onsubscription Permission (capability)`Subscriptions read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/v1/subscriptions/:id`	Update a subscription (change plan, quantity, proration).	write	`Subscriptions write`	Current
Limited to 200 quantity updates per subscription per hour. Acts onsubscription Permission (capability)`Subscriptions write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
DELETE	`/v1/subscriptions/:id`	Cancel a subscription, immediately or at period end.	write	`Subscriptions write`	Current
Fires customer.subscription.deleted. Acts onsubscription Permission (capability)`Subscriptions write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/subscriptions`	List all subscriptions (cursor-paginated).	read	`Subscriptions read`	Current
Read-only. Acts onsubscription Permission (capability)`Subscriptions read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Invoices Methods for working with invoices.5
POST	`/v1/invoices`	Create a draft invoice for a customer.	write	`Invoices write`	Current
Starts in draft until finalized. Acts oninvoice Permission (capability)`Invoices write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/invoices/:id`	Retrieve an invoice.	read	`Invoices read`	Current
Read-only. Acts oninvoice Permission (capability)`Invoices read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/v1/invoices/:id/finalize`	Finalize a draft invoice so it can be paid.	write	`Invoices write`	Current
Moves the invoice from draft to open. Acts oninvoice Permission (capability)`Invoices write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/v1/invoices/:id/pay`	Attempt payment on an open invoice.	write	`Invoices write`	Current
Fires invoice.paid or invoice.payment_failed. Acts oninvoice Permission (capability)`Invoices write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/invoices`	List all invoices (cursor-paginated).	read	`Invoices read`	Current
Read-only. Acts oninvoice Permission (capability)`Invoices read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Products Methods for working with products.3
POST	`/v1/products`	Create a product (a good or service being sold).	write	`Products write`	Current
A core catalog write. Acts onproduct Permission (capability)`Products write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/products/:id`	Retrieve a product.	read	`Products read`	Current
Read-only. Acts onproduct Permission (capability)`Products read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/products`	List all products (cursor-paginated).	read	`Products read`	Current
Read-only. Acts onproduct Permission (capability)`Products read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Prices Methods for working with prices.3
POST	`/v1/prices`	Create a price defining how much/how often to charge for a product.	write	`Prices write`	Current
A price is immutable on amount and interval once created. Acts onprice Permission (capability)`Prices write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/prices/:id`	Retrieve a price.	read	`Prices read`	Current
Read-only. Acts onprice Permission (capability)`Prices read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/prices`	List all prices (cursor-paginated).	read	`Prices read`	Current
Read-only. Acts onprice Permission (capability)`Prices read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Refunds Methods for working with refunds.3
POST	`/v1/refunds`	Refund a charge or PaymentIntent, fully or partially.	write	`Refunds write`	Current
Fires charge.refunded and refund.created. Acts onrefund Permission (capability)`Refunds write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/refunds/:id`	Retrieve a refund.	read	`Refunds read`	Current
Read-only. Acts onrefund Permission (capability)`Refunds read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/refunds`	List all refunds (cursor-paginated).	read	`Refunds read`	Current
Read-only. Acts onrefund Permission (capability)`Refunds read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Payouts Methods for working with payouts.3
POST	`/v1/payouts`	Create a payout to send funds from the Stripe balance to a bank account.	write	`Payouts write`	Current
The endpoint is limited to 15 create requests per second. Acts onpayout Permission (capability)`Payouts write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/payouts/:id`	Retrieve a payout.	read	`Payouts read`	Current
Read-only. Acts onpayout Permission (capability)`Payouts read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/payouts`	List all payouts (cursor-paginated).	read	`Payouts read`	Current
Read-only. Acts onpayout Permission (capability)`Payouts read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Balance Methods for working with the account balance.2
GET	`/v1/balance`	Retrieve the current account balance (available and pending).	read	`Balance read`	Current
Read-only. Acts onbalance Permission (capability)`Balance read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/balance_transactions`	List balance transactions (the entries that make up the balance).	read	`Balance Transactions read`	Current
Read-only. Acts onbalance_transaction Permission (capability)`Balance Transactions read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Checkout Methods for working with Checkout Sessions.4
POST	`/v1/checkout/sessions`	Create a Checkout Session, Stripe's hosted/embedded payment page.	write	`Checkout Sessions write`	Current
Returns a URL to redirect the customer to. Acts oncheckout.session Permission (capability)`Checkout Sessions write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/checkout/sessions/:id`	Retrieve a Checkout Session.	read	`Checkout Sessions read`	Current
Read-only. Acts oncheckout.session Permission (capability)`Checkout Sessions read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/v1/checkout/sessions/:id/expire`	Expire a Checkout Session so it can no longer be paid.	write	`Checkout Sessions write`	Current
Only works on open sessions. Acts oncheckout.session Permission (capability)`Checkout Sessions write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/checkout/sessions`	List all Checkout Sessions (cursor-paginated).	read	`Checkout Sessions read`	Current
Read-only. Acts oncheckout.session Permission (capability)`Checkout Sessions read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Payment Methods Methods for working with payment methods.4
POST	`/v1/payment_methods`	Create a PaymentMethod (card, bank, etc.).	write	`PaymentMethods write`	Current
Often created client-side, to keep card data off the integration's servers. Acts onpayment_method Permission (capability)`PaymentMethods write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/v1/payment_methods/:id/attach`	Attach a PaymentMethod to a customer for future use.	write	`PaymentMethods write`	Current
Required before reuse on a customer. Acts onpayment_method Permission (capability)`PaymentMethods write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
POST	`/v1/payment_methods/:id/detach`	Detach a PaymentMethod from a customer.	write	`PaymentMethods write`	Current
The PaymentMethod can no longer be used for the customer. Acts onpayment_method Permission (capability)`PaymentMethods write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/payment_methods`	List PaymentMethods attached to a customer.	read	`PaymentMethods read`	Current
Read-only. Acts onpayment_method Permission (capability)`PaymentMethods read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Events & Webhooks Methods for working with events and webhooks.2
GET	`/v1/events/:id`	Retrieve an Event, used to verify and re-fetch webhook payloads.	read	`Events read`	Current
Events are retained for 30 days. Acts onevent Permission (capability)`Events read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/events`	List Events (cursor-paginated), for polling or reconciliation.	read	`Events read`	Current
Read-only; 30-day retention. Acts onevent Permission (capability)`Events read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
Connect (Accounts) Methods for working with Connect accounts.3
POST	`/v1/accounts`	Create a connected account (Connect) for a platform's user.	write	`Connect / Account write`	Current
Connect platforms only; supports Standard, Express, and Custom controllers. Acts onaccount Permission (capability)`Connect / Account write` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/accounts/:id`	Retrieve a connected account.	read	`Connect / Account read`	Current
Read-only. Acts onaccount Permission (capability)`Connect / Account read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗
GET	`/v1/accounts`	List connected accounts on a Connect platform.	read	`Connect / Account read`	Current
Read-only; Connect platforms only. Acts onaccount Permission (capability)`Connect / Account read` VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗

No endpoints match those filters.

Webhooks

Webhook events.

Stripe can notify an app when something happens in an account, like a payment succeeding or a subscription ending. It sends an Event object describing what changed, so an integration learns about activity without polling.

Event	What it signals	Triggered by
`payment_intent.succeeded`	A PaymentIntent completed successfully and the payment is collected. An integration fulfills the order on this event.	`/v1/payment_intents/:id/confirm` `/v1/payment_intents/:id/capture`
`payment_intent.payment_failed`	A PaymentIntent's payment attempt failed, for example a card was declined.	`/v1/payment_intents/:id/confirm`
`charge.succeeded`	A charge succeeded. This complements payment_intent.succeeded for direct and legacy charge flows.	`/v1/charges` `/v1/payment_intents/:id/confirm`
`charge.refunded`	A charge was refunded, fully or partially.	`/v1/refunds`
`checkout.session.completed`	A Checkout Session was completed successfully. This is the primary signal to fulfill for hosted Checkout.	`/v1/checkout/sessions`
`customer.subscription.created`	A new subscription was created for a customer.	`/v1/subscriptions`
`customer.subscription.updated`	A subscription changed, like a plan switch, a trial moving to active, a quantity change, or a status change.	`/v1/subscriptions/:id`
`customer.subscription.deleted`	A subscription was canceled or ended. An integration deactivates the service on this event.	`/v1/subscriptions/:id`
`invoice.paid`	An invoice was paid, either because payment succeeded or because it was marked paid out-of-band.	`/v1/invoices/:id/pay` `/v1/subscriptions`
`invoice.payment_failed`	An invoice payment attempt failed, the point where dunning and retries begin.	`/v1/invoices/:id/pay` `/v1/subscriptions/:id`
`payout.paid`	A payout is expected to arrive in the destination bank account.	`/v1/payouts`
`customer.created`	A new customer object was created.	`/v1/customers`

No events match that search.

Rate limits & pagination

Rate limits, pagination & request size.

Stripe limits how fast and how much an app can call, by a request rate measured per second and by separate limits on how many requests run at once.

Request rate

Stripe meters requests by rate, not by a per-method cost or point weighting. A live account allows 100 requests per second across the account and 25 per second in sandbox (test) mode; an individual endpoint defaults to 25 per second unless it is set otherwise, with method-specific exceptions noted on the rows. Read (GET) volume is allocated separately from writes, which are not allocation-limited. A separate concurrency limit caps how many requests run at once, often reached by list or expand-heavy calls. Going over returns HTTP 429 with a Stripe-Rate-Limited-Reason header that names which limit was hit.

Pagination

A v1 list endpoint is cursor-based: limit sets the page size (default 10, range 1 to 100), starting_after takes an object id to fetch the next page, and ending_before takes one to fetch the previous page, with the two being mutually exclusive. A has_more field in the response signals whether more pages remain. Results come back in reverse-chronological order, and the SDKs offer auto-pagination. The v2 namespace uses a different pagination interface.

Request size

A list endpoint returns at most 100 objects per page, the maximum value of limit. An idempotency key may be up to 255 characters and is stored for at least 24 hours. An Event is retained and can be re-fetched for 30 days.

Errors

Status codes & error handling.

The status codes an agent should handle, and what to do about each.

Status	Code	Meaning	What to do
400	`invalid_request_error`	The request was bad: a parameter is missing or invalid, like parameter_missing or invalid_charge_amount.	Read the error message and doc_url, fix the parameters, and resend. The request is not retryable as-is.
401	`authentication_required / api_key_invalid`	No valid API key was provided.	Confirm a valid live or test key is being sent for the right mode, and rotate the key if it is compromised.
402	`card_declined`	The parameters were valid but the payment failed (card_error), for example card_declined, insufficient_funds, or expired_card.	Inspect decline_code and ask the customer for a different payment method. Don't blindly retry.
403	`permission / livemode_mismatch`	The API key lacks permission for this request, for example a restricted key without the needed resource scope, or a live and test mode mismatch.	Grant the resource permission on the restricted key, or use a key for the correct mode.
404	`resource_missing`	The requested object doesn't exist, or isn't visible to this key, account, or mode.	Verify the object ID and confirm it lives in the same mode and account.
409	`idempotency_error / resource_already_exists`	A conflict: an idempotency key was reused with different parameters, or a concurrent or duplicate request arrived.	Use a fresh idempotency key per distinct operation, and retry conflicts with backoff.
429	`rate_limit`	Too many requests arrived too quickly, or a concurrency limit was hit. The Stripe-Rate-Limited-Reason header names which limit.	Back off and retry with exponential backoff and jitter, and smooth the request rate.
500	`api_error`	An error on Stripe's side, which can also appear as 502, 503, or 504. It is rare.	Retry idempotently with backoff, and contact Stripe support if it persists.

Versioning & freshness

Version history.

Stripe pins a single dated version of its API per account, and ships named monthly releases alongside a preview track that carries breaking changes first.

Version history

What changed, and when

Latest version2026-05-27.dahlia

2026-05-27.dahliaCurrent version

Current GA release ('dahlia' monthly release)

Stripe pins a dated API version per account, set in Workbench, and a request can override it with the Stripe-Version header; a modern pinned SDK targets the version current at its release. Date-named releases (YYYY-MM-DD.release_name) ship roughly monthly, where named GA releases are backward-compatible and '.preview' releases may contain breaking changes for early testing.

What changed

Billing: discount eligibility and billing-schedule enhancements.
Connect: digital attestation improvements.
Elements updates and expanded payment-method support (Twint, Scalapay, Bizum).
No breaking changes in this GA release.

2026-04-22.dahlia

April 2026 GA release

A backward-compatible GA monthly release.

What changed

New payment methods: Sunbit BNPL, Pix recurring.
Managed Payments solution introduced.
Expanded stablecoin support.
No breaking changes.

2026-03-25.dahlia

March 2026 GA release (notable breaking changes)

A GA monthly release that did include some breaking changes, flagged in the changelog.

What changed

Checkout: UI mode enum values updated (breaking).
Connect: risk requirements added to the Capabilities API.
Elements: Address Element state-field formatting changed; elements.update() now returns a Promise.
Issuing: Visa card reference ID made optional.
Billing: retention-policy cancellation reason added.

2026-04-22.preview

April 2026 preview track

A preview release carries breaking changes first, so integrators can test before they reach GA.

What changed

Billing: validation added for meter event values exceeding 15 digits (breaking).
Payouts: Japan and China added as cross-border destinations; flow-specific reversal transaction categories.
Radar: radar_session made optional in the Payment Evaluations API.

2026-03-25.preview

March 2026 preview track

A preview track ahead of the March GA cut.

What changed

Payments: source type removed from Stripe balance payment methods (breaking).
Payouts: multicurrency restrictions for v2 payout methods; identity-field restrictions for Global Payouts.

Pin a version and move up on a schedule that suits the integration.

Stripe API changelog ↗

Questions

Stripe API, answered.

What's the difference between test and live keys?+

A key belongs to one mode. The sk_test_, rk_test_, and pk_test_ keys operate on simulated data in a sandbox where no real money moves, while sk_live_, rk_live_, and pk_live_ keys process real payments. Objects never cross modes, and a live secret or restricted key is revealed only once, when it is created.

How do I make requests safe to retry (idempotency)?+

A POST request can carry an Idempotency-Key header, any unique string up to 255 characters such as a UUID. Stripe stores the first response for at least 24 hours and replays it for any repeat with the same key, so a retry after a network blip won't double-charge. Reusing a key with different parameters returns an error.

How do I verify webhooks are really from Stripe?+

Each webhook carries a Stripe-Signature header. The receiver computes an HMAC over the raw request body using the endpoint's signing secret (whsec_...) and compares it, or uses the SDK's constructEvent or Webhook.verify helper. The check runs on the raw, unparsed body, and a mismatch is rejected to prevent spoofing.

How does API versioning / pinning work?+

An account has one default dated version, set in Workbench, and every request uses it unless overridden with the Stripe-Version header per request, or unless a pinned SDK targets its own version. Upgrades are deliberate and tested in Workbench first, because a major or preview version can include breaking changes.

Should I use PaymentIntents or Charges?+

PaymentIntents is the modern flow. The Charges create API is legacy and doesn't handle requirements like Strong Customer Authentication (3D Secure) or asynchronous payment methods. A PaymentIntent orchestrates authentication, capture, and retries, and a successful one still produces a Charge object that can be inspected.

What are restricted keys and when should I use them?+

A restricted key (rk_) is a server key that grants each resource only the access it needs, set to None, Read, or Write. Using one everywhere instead of a full secret key limits the damage to its scopes if a key leaks. Restricted keys are created and managed on the API keys page in the Dashboard.

How does Stripe Connect authentication work?+

A platform can act on a connected account in two ways. One is to use its own secret or restricted key plus a Stripe-Account: acct_... header. The other, for Standard accounts the platform doesn't own, is the OAuth flow at connect.stripe.com/oauth/authorize, with a scope of read_only or read_write, exchanging the code at /oauth/token for an access token tied to that account.

What is Bollard AI?

Control what every AI agent can do in Stripe.

Bollard AI sits between a team's AI agents and Stripe. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.

Set read, write, or full access per agent, never a shared Stripe key.
Denied by default, so an agent reaches only what has been explicitly allowed.
Every call recorded in plain English: who, what, where, and the decision.

Control Stripe access in Bollard Browse all APIs →

Stripe

Billing Agent

View payments ResourceOffReadFull use

Issue refunds ActionOffReadFull use

Customers ResourceOffReadFull use

Per-agent access, set in Bollard AI, not in Stripe

How the Stripe API works.

Connection & authentication methods.

REST API

Webhooks

MCP server

Secret API key

Restricted API key

Publishable API key

Connect (OAuth)

What an AI agent can do in Stripe.

Payments (PaymentIntents)

Charges

Customers

Subscriptions

Invoices

Products

Prices

Refunds

Payouts

Balance

Checkout

Payment Methods

Events & Webhooks

Connect (Accounts)

Every Stripe API method.

Payments (PaymentIntents)

Charges

Customers

Subscriptions

Invoices

Products

Prices

Refunds

Payouts

Balance

Checkout

Payment Methods

Events & Webhooks

Connect (Accounts)

Webhook events.

Rate limits, pagination & request size.

Request rate

Pagination

Request size

Status codes & error handling.

Version history.

What changed, and when

Stripe API, answered.

More finance API guides for agents

FreshBooks

Chargebee

Razorpay

Recurly

Square

BILL

Control what every AI agent can do in Stripe.