System status

v2 to v3 migration

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

📘

NOTE

The BILL v3 API is currently in beta and is subject to improvements and changes. All improvements and changes will be documented.

For any BILL v2 API feature that is not available with the v3 API, feel free to continue to using the v2 API for that feature.

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.

v2v3
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.

v2v3
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.

Updated about 14 hours ago