API Versioning
How to pin your integration to a specific API version and upgrade safely.
What this is and who needs it
EPD evolves: new fields land, old ones move, behaviors get tightened. A breaking change should never reach your code by accident. API versioning lets you pin to a known-good date and choose when to upgrade.
If you write any code against EPD, you should pin a version. It costs nothing now and saves outage minutes later.
How versions work
The URL prefix is always /v1/. The version is sent in the epd-version request header (case-insensitive):
epd-version: 2026-02-11
A version is a date — the date the change set was published. Pinning to that date means EPD will keep returning the request and response shape that was current on that date, even after newer versions ship.
Current version: 2026-02-11
Resolution order
Whenever EPD receives a request, it picks a version using the first rule that matches:
| Priority | Source | Description |
|---|---|---|
| 1 | epd-version header | Per-request override |
| 2 | Merchant pinned version | Stored on your account in the Merchant Portal |
| 3 | Latest published version | Default for new merchants who have set neither |
Always send the epd-version header. Relying on the merchant pin alone makes one ops mistake (someone bumps the pin) into a production incident.
Lifecycle of a version
| Status | Behavior |
|---|---|
current | The latest published version. Used when nothing else is specified. |
supported | Older but fully working. No warnings. |
deprecated | Still works. Sends Deprecation and Sunset HTTP headers warning of a future cutoff. |
sunset | No longer accepted. Returns 400 Bad Request with error.code = api_version_sunset. |
Errors related to versioning
| Code | Status | Meaning |
|---|---|---|
invalid_api_version | 400 | The epd-version header is not a recognised version date. |
api_version_sunset | 400 | The version is past its sunset date and is no longer accepted. Upgrade. |
Upgrading
Each version date documents added fields, removed fields, and behavior changes. Most upgrades touch only one or two surfaces of your code — read the diff between your current pin and the new date before bumping.
Override epd-version to the new date in your sandbox env. Run your full integration test suite.
Bump the constant your client sends. Deploy. The merchant pin can be updated later, or left in place as a safety net.
EPD supports overlapping deployments — different services on your side can run different versions during a rollout. Pin per-service, not per-merchant, when you need flexibility.