---
title: "API versioning policy"
description: "How iwoca manages API versions, upgrades, and deprecation"
---

> For the complete documentation index, see [llms.txt](/llms.txt).

## What this policy covers

This policy outlines how iwoca manages API versions and upgrades.
It covers how we handle backwards incompatible API changes and how we communicate the deprecation and removal of older versions.

## Versioning strategy

iwoca will not make backwards incompatible changes to current API versions.

<AccordionGroup>
  <Accordion title="Backwards compatible changes">
    Backwards compatible changes may be released into existing versions.
    These changes include:

    - Adding new endpoints.
    - Adding new optional fields to request bodies or parameters.
    - Adding new fields to existing API responses.
      Note that this does not include changing the structure of existing fields, which would be considered a backwards incompatible change.
    - Making changes to the OpenAPI schema for the API when this does not affect the behaviour of the API.
  </Accordion>
  <Accordion title="Backwards incompatible changes">
    When iwoca makes a backwards incompatible change, it will be released as a new numbered version of the API.
    This approach ensures that existing integrations remain functional and users have the option to upgrade and benefit from new features.
  </Accordion>
</AccordionGroup>

## Version numbering

iwoca uses a numbering system to mark API versions.
If we make a backwards compatible change, it will be released to existing versions and we will not increment the version number.

| Type | Description | Example |
|---|---|---|
| **Minor** | Most common upgrade. Released for smaller backwards incompatible changes. | v2.1 → v2.2 |
| **Major** | Significant structural changes to the API. | v1.0 → v2.0 |

## Version release schedule

iwoca does not follow a set schedule for releasing new versions.
New versions are released when we want to add a new feature that would require a backwards incompatible change.
We may also use new versions to simplify the API, for example by removing fields that are no longer necessary.

## Version deprecation policy

iwoca supports multiple versions of the API at the same time, but occasionally previous versions of the API may be deprecated when we release a new version.
iwoca will notify partners when a version of the API is deprecated.

<Warning>
iwoca will give at least **one year's notice** before a deprecated version is made unavailable.
</Warning>

## How to upgrade API versions

If you're planning to upgrade to a new API version or need assistance, please contact us via your usual channel or at [partners@iwoca.co.uk](mailto:partners@iwoca.co.uk).

<Info>
Your existing API tokens will work across all versions – you don't need to request replacement tokens during an upgrade.
Ask us for a summary of changes between versions.
</Info>