API versions
Build your integration once. When we change the API later, your calls keep getting the answers they got on the day you built it.
Every business is pinned to an API version, a date. It is set when the
business registers and it only changes when you upgrade it yourself. The
current version is 2026-10-21.
What a version covers
Pinned to your version:
- Every endpoint you call with your API key: creating a hosted checkout session, decline recovery, the session status lookup, refunding, cancelling and reminding. The full list is in the API reference.
- Every webhook we send you: which events, and the shape of
their
data.
The endpoints you call with a signed-in session (the ones the dashboard uses) are kept backwards compatible too, but they are not pinned to a version. Build server-to-server integrations on your API key.
Changes that do not need a new version
These can happen at any time, on every version, because a well-built integration does not break on them:
- A new endpoint.
- A new optional request field.
- A new field in a response or a webhook payload.
- A new value for
codeon an error. - A new value for
currency, when we start accepting another currency. - A change to the wording of an error's
errormessage. - New response headers.
So, to be safe on every version:
- Ignore fields you do not recognise. Do not reject a payload because it has more in it than you expected.
- Branch on an error's status and
code, never on its message text. - Treat
codeandcurrencyas open lists: handle the ones you know and fall back sensibly for the rest.
Changes that do need a new version
Anything that could break code that worked yesterday comes out as a new, dated version, and your business stays where it is:
- Removing or renaming a field, or changing its type or unit.
- Making an optional request field required, or refusing a value that used to be accepted.
- Changing a status code or an error
code. - A new value in a field you might
switchon, such as a split's or a participant'sstatus. The values each version can send are fixed for that version. - A new webhook event type. You only get event types that existed at your version.
- Changing what an existing call does in a way your server can see.
Seeing your version
- Dashboard: Settings, Developers shows the version your business is on.
- Every API-key response carries it in a header:
X-SharePay-Version: 2026-10-21. - Every webhook carries it too, in the same header. See Webhooks.
GET /api/merchants/mereturnsapi_versionandlatest_api_version.
Trying a newer version first
Send the version you want on any API-key call, and that one call is answered at it. Nothing else changes:
curl https://api.share-pay.co.uk/api/merchants/checkout/sessions \
-H "x-merchant-api-key: sp_prod_..." \
-H "X-SharePay-Version: 2026-10-21" \
-H "Content-Type: application/json" \
-d '{"amount": 120, "order_reference": "ORDER-123", "return_url": "https://yourshop.co.uk/thanks"}'
A version we do not know is refused with 400 invalid_api_version, rather than
answered at a different version than the one you asked for. Webhooks always
follow your business's version, not this header.
Upgrading
When a newer version exists, Settings, Developers offers to upgrade. An Owner
or Admin can do it, from the dashboard or with
POST /api/merchants/api-version/upgrade. It moves your business to the latest
version straight away, for API calls and webhooks, in test and live.
Read the changelog below first, and try your integration against the new version with the header above before you upgrade.
If something breaks, you can go back for 72 hours after upgrading, from the
same page or with POST /api/merchants/api-version/rollback. After that the
upgrade stays, though you can still send an older version in the header on a
call while you fix things.
Webhooks queued before an upgrade or a rollback keep the shape they were
queued with, including when they are retried or you press Resend. The
X-SharePay-Version header on each delivery says which shape that is.
The exception: law and security
Very rarely, we may have to change something on every version at once: because the law requires it, or because leaving the old behaviour in place would put your customers' money or data at risk. When that happens we tell every affected business by email, before the change where we can, and with as much notice as the situation allows. For an active security problem we may have to act first and tell you straight after. Every such change is listed in the changelog below, marked as applying to all versions.
Your fees and your Merchant Agreement are not part of an API version. Changes to those are made under the agreement itself.
Changelog
| Version | What changed |
|---|---|
2026-10-21 | The first version: the API exactly as documented on this date. Every business that existed before versioning is pinned here. |