---
title: "Pin the provider's API version · Agent Wranglers"
url: https://agentwranglers.se/playbook/payments/payment-events-and-reconciliation/provider-api-version
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Pin the provider's API version

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

For AI agents: [llms.txt](https://agentwranglers.se/llms.txt) is a short guide that sends you to the rules your problem needs, and [rules.json](https://agentwranglers.se/playbook/payments/rules.json) holds every rule of this playbook as JSON.

- Level: Recommended
- Chapter: [Payment events and reconciliation](https://agentwranglers.se/playbook/payments/payment-events-and-reconciliation)
- Rule: Set the provider's API version in your code and on each webhook endpoint, and keep both the same. Upgrade it on purpose after the tests pass on the new version.
- Applies when: The project it takes payments.
- How: Without a pinned version, requests and webhook events follow the account's default version, which someone can change in the dashboard. Stripe, for example, ships a new version every month and breaking changes twice a year. Many SDKs pin the version they were built for, so an SDK upgrade is an API upgrade. Create each webhook endpoint with the same version as the SDK. To upgrade, run the payment tests against the new version in test mode first. Update the SDK as [Update dependencies in small automatic steps](https://agentwranglers.se/playbook/engineering/version-control-and-review/automated-dependency-updates) describes.
- Check: The code sets the API version in one constant, and the provider's webhook endpoint list shows that same version. A test fails when the SDK reports a different version than the constant.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
const PAYMENT_API_VERSION = '2026-09-30.endive'
const stripe = new Stripe(process.env.PAYMENT_API_KEY, { apiVersion: PAYMENT_API_VERSION })

await stripe.webhookEndpoints.create({
  url: 'https://example.com/webhooks/payments',
  enabled_events: ['payment_intent.succeeded', 'charge.refunded'],
  api_version: PAYMENT_API_VERSION,
})
```

### Python example

```python
PAYMENT_API_VERSION = "2026-09-30.endive"
stripe.api_version = PAYMENT_API_VERSION

stripe.WebhookEndpoint.create(
    url="https://example.com/webhooks/payments",
    enabled_events=["payment_intent.succeeded", "charge.refunded"],
    api_version=PAYMENT_API_VERSION,
)
```

## Sources

- [Stripe API versioning](https://docs.stripe.com/api/versioning)

## Related rules

- [Update dependencies in small automatic steps](https://agentwranglers.se/playbook/engineering/version-control-and-review/automated-dependency-updates) in Engineering
- [Use Stripe for payments](https://agentwranglers.se/playbook/stack/product-services/stripe-payments) in Software choices

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/payments/payment-events-and-reconciliation/provider-api-version">Agent Wranglers payments playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Give each person the smallest role in the provider dashboard](https://agentwranglers.se/playbook/payments/payment-events-and-reconciliation/provider-dashboard-access)
- [Payment events and reconciliation](https://agentwranglers.se/playbook/payments/payment-events-and-reconciliation)