v2 to v3 migration

In this guide, we help you with your migration from the BILL v2 API to the v3 API.

Migration checklist

Review the migration checklist for identifying improvements and changes in the v3 API.

Identify changes

Familiarize yourself with the v3 API design in the API reference. The v3 API follows the REST standard.
Review the Guides section for information on standard use cases available with the v3 API.
In the Recipes section, leverage the sample code and logic available for workflows with the v3 API.
List the v2 endpoints that your integration uses, and then look for the equivalent v3 endpoints in the next sections.

Test and update your code

Test with the v3 endpoints for your use case. Note the new request format, response format, request validations, and error responses for each operation.
Update your code by replacing the v2 endpoints with the equivalent v3 endpoints.

API base URL changes

The v3 base URLs point to new locations.

v2	v3
Sandbox: `https://api-sandbox.bill.com/api/v2`	Sandbox: `https://gateway.stage.bill.com/connect/v3`
Production: `https://api.bill.com/api/v2/`	Production: `https://gateway.prod.bill.com/connect/v3`

API header value changes

The HTTP header has a name, colon (:), and value. In v3, the HTTP header value has been updated.

v2	v3
The HTTP header value in your v3 API requests is `content-type: application/x-www-form-urlencoded`.	The HTTP header value in your v3 API requests is `content-type: application/json`.
When testing with API calls in Postman, set the Body value as x-www-form-urlencoded.	When testing with API calls in Postman, set the Body value as raw for POST, PATCH, and PUT requests. For GET requests, use Params.

Mapping between v2 and v3

In this section, we map the functionality and features between v2 and v3. Note that this table provides key highlights. See the API reference for detailed information about each v3 endpoint.