API Versioning & Upgrading
This article covers API Versions, usage, and how to upgrade.
In general, we handle API versioning by using dated version. When we make backwards-incompatible changes to the WePay API, the release date is used. Given that this is a header value, your app will continue to be on the current version of the API to avoid breaking your code.
Your app’s WePay API Version determines the behavior that you see from the API. It affects the parameters you can pass in, the response that you get back, and the IPNs you receive.
API Version Format
WePay API versions are dates with format yyyy-mm-dd. Ex: 2019-04-03. You will pass this as a header in your API calls.
API-Version: 2019-04-03
Current API Version
The current version of the WePay API is 2019-04-03. Full list of API versions can be found at our - Change Log
Check API Version
You can check your application’s API version on the configure tab of your application dashboard:
Upgrade API Version
There are two ways to upgrade your application’s API version. A full upgrade affects all of the api calls you will make. If you are not ready for a full upgrade, you can upgrade gradually by specifying an API version by API call.
Full Upgrade
You should opt for a full upgrade if the new changes do not affect your app or if you have already changed your code to accommodate them. You can start using the latest version of the WePay API by clicking on the “Upgrade” button in the “API Version” section of your application dashboard’s configure tab. Be careful to change your code beforehand to adhere to the changes made in the new version; if you do not, your code will break!
Gradual Upgrade
Choose the gradual upgrade option to change one api call request at a time. Send an 'Api-Version' header parameter when making an API call request, and our API will send back a response appropriate to the version you specify in this header.
For example, if a change occurs on October 15, 2014, you can test just the /account call changes by setting the /account api call ‘Api-Version’ header to 2014-10-15. Note that all requests without the Api-Version header will use the API version set on your application dashboard.
To complete the gradual upgrade, confirm a full upgrade after migrating all relevant calls to the new version.
If you are using one of our SDKs, you can set the API Version per call by passing the API Version as a parameter during initialization functions.
Warning
Starting with version 2016-07-13, an application can only use the ‘Api-Version’ header to make an API call request equal to the API version set on the application’s dashboard and one version above it. If an application attempts to make an API call request with the ‘Api-Version’ header set to below the application’s version, or more than 1 version above the application’s version, then the API will respond back with an error code of 1016. This will break an application’s functionality if it is not properly set up.
See sample code below for an example on setting the Api-Version to 2017-02-01 for the /account API call.
- PHP
- cURL
- Ruby
- Python
Breaking Changes
We consider the below API behaviors as breaking changes that warrant a new API version.
- Removing resources
- Removing request parameters
- Adding new required request parameters
- Removing response parameters in existing API responses
- Changing the behavior of IPNs
- Changing permissions for existing resources