How to Upgrade API Version

This tutorial explains how you can upgrade your application to the latest version of the WePay API.

Check your current API Version

Make sure to check your application’s API Version on the configure tab of your application’s dashboard:

Configure page with API Versioning upgrade button

Each new WePay API version introduces changes that may break your API call request code. Before you upgrade to a new version of the WePay API, you should look through the Change Log for information on breaking changes that you might have to consider in your code.

Upgrade to new 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 per api call request.

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.


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 (the current version of the WePay API) for the /account API call.

  • PHP
  • cURL
  • Ruby
  • Python


Not sure what API Version to set? Check out the Change Log.