> **Description:** Learn about Vipps MobilePay API versioning, deprecation policies, and how to stay current with API updates and changes.

# API lifecycle

Vipps MobilePay APIs are versioned, maintained, and deprecated on a predictable schedule. This page explains the commitments we make to you, what to expect when APIs change, and what your team needs to do to stay current.

## Key commitments

| What | Our commitment |
|---|---|
| **Breaking change notice** | Minimum **4 months** notice before a major version is deprecated. |
| **How we'll reach you** | Email to your registered technical contact; direct outreach from your partner manager or KAM if applicable. |
| **Minor and patch updates** | Non-breaking. We expect you to update within **30 days** of release. |
| **Backwards compatibility** | We never remove or change existing fields without a new major version. New fields may be added at any time without notice. |

**Keep your contact information current**

Deprecation notices are sent to the technical contact registered on your merchant account. If that information is out of date, you may miss critical communications. Update it at [help.vippsmobilepay.com](https://help.vippsmobilepay.com/).

**Subscribe to stay informed:** The [technical updates newsletter](https://developer.vippsmobilepay.com/docs/technical-updates/README.md) is the earliest place deprecation announcements are published. Strongly recommended for anyone responsible for maintaining an integration.

---

## Versioning

Our APIs follow [Semantic Versioning](https://semver.org) standards:

> Given a version number MAJOR.MINOR.PATCH, increment the:
>
> * **MAJOR** version when you make incompatible API changes
> * **MINOR** version when you add functionality in a backwards compatible manner
> * **PATCH** version when you make backwards compatible bug fixes

### Version numbers in endpoint URIs

API versions are included directly in the endpoint path using only the major version number:

* `GET:/someapi/v1/some/more/path`
* `GET:/someapi/v2/some/more/path`

**Example:** When API version `2.3.4` is released, you'll use `/v2/` in the endpoint path.

## Version lifecycle

APIs evolve over time. Keep your applications updated with the latest versions for optimal performance and new features.

### Major version

A major version is officially supported until the date when it becomes deprecated.

Major versions introduce breaking changes that are incompatible with previous versions.
See [Deprecation notice](#deprecation-notice) for details about the deprecation process.

### Minor version

A minor version is automatically superseded by a newer minor version.
If a customer uses version `2.1.0`, that version is automatically
superseded when version `2.2.0` is available.
There will be no bug fixes or other improvements to a minor version that
has been superseded.

We expect you to update to the latest minor version within 30 days.

### Patch version

A patch version fixes one or more small problems, such as correcting a
small bug, so the API works as intended and documented in the first place.

We expect you to update to the latest patch within 30 days.

## Deprecation notice

**Minimum notice period: 4 months**

When we deprecate an API or major version, we provide at least four months notice before the deprecation date.

### Notification channels

We use multiple channels to ensure you're informed about deprecations:

#### 1. Technical updates newsletter

[Review technical updates](https://developer.vippsmobilepay.com/docs/technical-updates/README.md) for deprecation announcements as soon as decisions are made. **Strongly recommended for all developers.**

#### 2. Personal contact

**For partners and key accounts:** Your partner manager or Key Account Manager (KAM) will contact you directly about deprecations.

#### 3. Email notifications

We attempt to email the technical contact registered for your merchant account. If no technical contact is registered, we'll contact the main account contact.

### APIs

The API version is included in the path: `v1`, `v2`, and so on.
Only the major version is specified.

### API documentation

When the API specifications are updated, we version it according to
the mentioned [versioning standards](#versioning).

## Backwards compatibility

We strive to improve existing APIs while also maintaining backwards compatibility.

We consider the following changes to be backwards compatible:

* [Adding an optional field to a request](#adding-an-optional-field-to-a-request)
* [Adding an optional field to a response](#adding-an-optional-field-to-a-response)
* [Adding a new enum value](#adding-a-new-enum-value)
* [Relaxing some constraints on an existing request parameter](#relaxing-some-constraints-on-an-existing-request-parameter)
* [Adding a new response parameter to the API response](#adding-a-new-response-parameter-to-the-api-response)
* [Changing the order in which parameters are returned in existing API responses](#changing-the-order-in-which-parameters-are-returned-in-existing-api-responses)
* [Correcting faulty functionality in edge cases](#correcting-faulty-functionality-in-edge-cases)
* [Adjusting the rate limit for an API](#adjusting-the-rate-limit-for-an-api)

### Adding an optional field to a request

An optional parameter for a request is considered a backwards compatible change.
The caller may choose to send the new, optional parameter, but there is no
obligation to do so. There is no change in the API's functionality if the
new, optional parameter is omitted.

The parameter can be added as part of the request body, as a URL parameter, or
an HTTP header field.

Some optional parameters may offer additional or improved functionality, but
the API will never offer less than before the optional parameter was added.

#### Example

We may add a `msisdn` field to support international phone numbers,
in addition to Norwegian-only phone numbers:

Version 2.0.0:

```json
  "customerInfo": {
    "mobileNumber": 4712345678
  }
```

Version 2.1.0:

```json
  "customerInfo": {
    "mobileNumber": 12345678,
    "msisdn": 4712345678
  }
```

### Adding an optional field to a response

An optional parameter for a response is considered a backwards compatible change.

The parameter can be added as part of the response body or an HTTP header field.

It is the caller's responsibility to manage the response in a way that
correctly handles new, optional parameters. This is normally done automatically,
but we want to explicitly mention this.

#### Example of optional field

We may add a `type` field to the `address` object:

Version 2.0.0:

```json
"address": {
  "addressLine1": "Robert Levins gate 5",
  "city": "Oslo",
  "postCode": "0154",
  "country": "Norway"
  }
```

Version 2.1.0:

```json
"address": {
  "addressLine1": "Robert Levins gate 5",
  "city": "Oslo",
  "postCode": "0154",
  "country": "Norway",
  "type": "business"
  }
```

### Adding a new enum value

The value may be added either in the request or in the response.

Response parsing must be robust: Ignore any unknown fields or enum values
received as part of API responses.

### Relaxing some constraints on an existing request parameter

For example, making it optional.

### Adding a new response parameter to the API response

Response parsing must be robust, and able to handle new parameters.

The parameter can be added as part of the request body, as a URL parameter, or
an HTTP header field.

### Changing the order in which parameters are returned in existing API responses

Response parsing must be robust.

### Correcting faulty functionality in edge cases

If the API has offered unintended, undocumented functionality, we consider it a
backwards compatible change to correct it.

## Breaking changes

Changes that are incompatible with previous versions of an API require
a new major version. This means a bump from `2.3.4` to `3.0.0`.

The API endpoints will also get a new version parameter in the path, for example:
from `v2` to `v3`.

Breaking changes include:

* [Changing the properties of an object](#changing-the-properties-of-an-object)
* [Adding a new required parameter](#adding-a-new-required-parameter)
* [Changing an endpoint's URL](#changing-an-endpoints-url)

### Changing the properties of an object

A change in the format for `country` from the full name of the country
(`Norway`) to ISO 3166 (`NO`) is considered a breaking change, as
it requires a change in code that uses the API.

Version 2.0.0:

```json
"address": {
  "addressLine1": "Robert Levins gate 5",
  "city": "Oslo",
  "postCode": "0154",
  "country": "Norway"
  }
```

Version 3.0.0:

```json
"address": {
  "addressLine1": "Robert Levins gate 5",
  "city": "Oslo",
  "postCode": "0154",
  "country": "NO",
  }
```

If the ISO 3166 country code was *added* as `countryCode` in addition to the existing `country`,
it would be a non-breaking change, and only a minor version:

Version 2.1.0:

```json
"address": {
  "addressLine1": "Robert Levins gate 5",
  "city": "Oslo",
  "postCode": "0154",
  "country": "Norway"
  "countryCode": "NO",
  }
```

### Adding a new required parameter

A new required parameter that results in previously valid requests no longer
being valid, is considered a breaking change.

### Changing an endpoint's URL

It is considered a breaking change to change from `POST:/accesstoken/get` to
`POST:/accesstokens`.

### Adjusting the rate limit for an API

Our
[API rate limits](https://developer.vippsmobilepay.com/docs/knowledge-base/polling-guidelines.md#rate-limits)
are set to a level that prevents obvious misuse, and the APIs respond with
`HTTP 429 Too Many Requests` when the limits are exceeded.

We may adjust the rate limits when we see that APIs are used in an obviously incorrect way,
and do not consider this a breaking change of the API itself.

> **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).