On This Page
On This Page

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:

Configure page with API Versioning upgrade button

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