Skip to main content

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 code on an error.
  • A new value for currency, when we start accepting another currency.
  • A change to the wording of an error's error message.
  • 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 code and currency as 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 switch on, such as a split's or a participant's status. 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/me returns api_version and latest_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​

VersionWhat changed
2026-10-21The first version: the API exactly as documented on this date. Every business that existed before versioning is pinned here.