Stripe versions its API by date. Each new version may add features, change defaults or rename fields. ActiveManage pins to a specific API version so that Stripe's behaviour cannot change underneath you without warning.
Why Pinning Matters
- Stripe sometimes changes default behaviour — e.g. a webhook event payload gains new fields, or a response field becomes optional.
- Without pinning, your live integration would experience these changes silently and could break.
- With pinning, you get the stable behaviour you tested against; Stripe maintains backwards compat per version.
Reading the Current Pinned Version
Open Architect Panel → Stripe Integration → API Version. The current pinned version is shown alongside the release date and a link to Stripe's changelog.
When to Upgrade
- A new feature requires a newer version — e.g. Apple Pay Domain Verification added in a specific release.
- Quarterly hygiene — review pinned version every 3-6 months to avoid falling far behind.
- Stripe deprecation notice — Stripe occasionally retires very old versions; act before the cutoff.
Upgrade Process
- Read Stripe's changelog from your current version to the target.
- List every breaking change that affects features you use.
- Update the pinned version in a staging environment first.
- Run your integration test suite, including webhook event reception.
- Deploy to production during a low-traffic window.
- Monitor the Stripe dashboard for errors over the next 24 hours.
Worked Examples
- Conservative SaaS: Upgrade once a year after a thorough test cycle.
- Active marketplace: Upgrade quarterly to access new features (e.g. Tax automation).
- Multi-region app: Pin to the version with the broadest payment method support for the regions you serve.