API v2 overview

The Stripe API provides two namespaces that contain different sets of endpoints:

• API v1: The /v1 namespace includes most of the existing Stripe API today.
• API v2: The /v2 namespace includes endpoints that use /v2 design patterns.

Key differences between the v1 and v2 namespace

SDKs that support API v2

All server-side SDKs support APIs in the /v2 namespace.

Using API v2 with the Stripe CLI

Use stripe trigger and stripe listen to test your integration’s event handling. You can’t access APIs in the /v2 namespace using the Stripe CLI.

SDK, CLI, and API versioning

SDKs and the Stripe CLI automatically include an API version for all requests. After you update your SDK or CLI version, Stripe simultaneously updates the API version of your requests and responses.

Include Stripe-Version without SDK or CLI

All API requests to the API /v2 namespace must include the Stripe-Version header to specify the underlying API version.

For example, a curl request using API version 2024-09-30.acacia looks like:

curl -G https://api.stripe.com/v2/core/events \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2024-09-30.acacia" \
  -d object_id=fa_123

Using APIs from the v1 and v2 namespaces in the same integration

You can use any combination of APIs in the /v1 or /v2 namespace in the same integration.

StripeClient stripe = new StripeClient("{{YOUR__API_KEY}}");

# Call a v2 API
var event = stripe.V2.Core.Events.Retrieve("evt_123");

# Call a v1 API
var customer = stripe.V1.Customers.Retrieve("cus_123");

If you’re not using an official SDK or the CLI, always include the namespace in the URL path for your API calls. For example:

# Call a v2 API
curl https://api.stripe.com/v2/core/events?object_id=mtr_123

# Call a v1 API
curl https://api.stripe.com/v1/charges -d amount=2000 -d currency=usd

List pagination

APIs within the /v2 namespace (for example, GET /v2/core/events) contain a different pagination interface compared to those in the /v1 namespace.

• The previous_page_url property returns a URL to fetch the previous page of the list. If there are no previous pages, the value is null.
• The next_page_url property returns a URL to fetch the next page of the list. If there are no more pages, the value is null.

You can use these URLs to make requests without using our SDKs. Conversely, when you use our SDKs, you don’t need to use these URLs because the SDKs handle auto-pagination automatically.

You can’t change list filters after the first request.

StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}");

var options = new Stripe.V2.Core.EventListOptions
{
  ObjectId = "mtr_123",
};

foreach (Stripe.V2.Core.Events evt in stripe.V2.Core.Events.ListAutoPaging(options)) {
  // process event object
}

Idempotency

APIs in the /v2 namespace provide improved support for idempotency behavior, preventing unintended side effects when requests are performed multiple times using the same idempotency key. When the API receives two requests with the same idempotency key:

• If the first request succeeded, the API skips making new changes and returns an updated response.
• If the first request failed (or partially failed), the API re-executes the failed requests and returns the new response.
• In the rare event that it’s no longer possible for an idempotent replay to succeed, the API returns an error explaining why.

Two requests are considered idempotent if the following are all true:

• Use the same idempotency key for the same API
• Occur in the scope of the same account or sandbox
• Occur within the last 30 days of each other

To specify an idempotency key, use the Idempotency-Key header and provide a unique value to represent the operation (we recommend a UUID). If no key is provided, Stripe automatically generates a UUID for you.

All POST and DELETE API v2 requests accept idempotency keys and behave idempotently. GET requests are idempotent by definition, so sending an idempotency key has no effect.

Idempotency differences between API v1 and API v2

API v1 and API v2 idempotency have a few key differences:

• API v1 only supports idempotent replay for POST requests. API v2 supports all POST and DELETE requests.
• Two requests are considered idempotent for:
  • API v1 if they use the same idempotency key and occur within 24 hours of each other.
  • API v2 if they use the same idempotency key, are made to the same API, occur within the scope of the account or sandbox, and are made within 30 days of each other.
• When you provide the same idempotency key for two requests:
  • API v1 always returns the previously-saved response of the first API request, even if it was an error.
  • API v2 attempts to retry any failed requests without producing side effects (any extraneous change or observable behavior that occurs as a result of an API call) and provide an updated response.

Making idempotent requests

Using the SDK, provide an idempotency key with the idempotencyKey property in API requests.

For example, to make an API request with a specific idempotency key:

StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}");

string idempotencyKey = "unique-idempotency-key";
var result = stripe.V2.Example.Create(
  new Stripe.V2.ExampleCreateOptions { Name = "My example" },
  new RequestOptions { IdempotencyKey = idempotencyKey };
);

If you’re not using a SDK or the CLI, requests can include the Idempotency-Key header:

curl https://api.stripe.com/v2/examples \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: {{STRIPE_API_VERSION}}" \
  -H "Idempotency-Key: unique-idempotency-key" \
  -d <JSON request body>

Limitations

• Test mode doesn’t support /v2; however, you can use a sandbox to test within this namespace.
• Currently, Stripe only generates thin events using /v2 endpoints and resources.
• You can only see request logs generated by API v2 in Workbench, not in the Developers Dashboard.