On September 13, 2024, BILL will update the current API certificate for api.bill.com. Updating API certificates every 90 days is a common practice for maintaining a high level of security. We expect no impact to API services unless you are pinning certificates or are managing them manually.

BEST PRACTICE: Avoid certificate pinning

We highly recommend that you do not pin any BILL API certificates. Certificate pinning is not scalable, requires maintenance, and can cause downtime for your integrations in the production environment.

If you are pinning certificates for api.bill.com, update the certificate to use all five Root CAs listed on https://pki.goog/repository/ (GTS Root R1, GTS Root R2, GTS Root R3, GTS Root R4, and GlobalSign R4).

For questions or concerns, email us at [email protected].

We have introduced new features for the BILL webhook API. BILL partners can now perform subscription and event operations at the partner level.

As a BILL partner, when you create a subscription for events, you get event notifications for all the organizations created with your partner appKey. To create a subscription at the partner level, simply set the required header values. The base URL and body parameters in the POST /v3/subscriptions request are the same for partner users and organization users.

We have introduced a set of Multi-Factor Authentication (MFA) API endpoints. There are two stages in the BILL MFA process.

1. MFA setup: Add a valid phone number for setting up MFA in the organization (with POST /v3/mfa/setup), and then complete the setup by validating the entered phone number (with POST /v3/mfa/validate). At this point, the phone number is registered for the MFA sign in operation.

2. MFA sign in: Generate an MFA challenge (with POST /v3/mfa/challenge), and then complete MFA sign in by validating the MFA challenge (with POST /v3/mfa/challenge/validate). At this point, your API session is MFA trusted.

The PENDING risk verification decision status is now updated to IN_PROGRESS. We made this update for further simplifying the meaning of different status values.

See POST /v3/risk-verifications in the API reference for more information.

In the payments API response, you now receive information about the bills that a payment amount is applied to.

When you pay a bill with POST /v3/payments or when you pay multiple bills with one POST /v3/payments/bulk, you now see a billPayments object in the response. For each bill payment, the billPayment object includes the bill payment id, bill id, and amount applied to the bill.

See Payments for more information.

We have added pagination in the get list of event notifications (GET /v3/events/subscription/{subscriptionId}) and get list of subscriptions (GET /v3/subscriptions) endpoints.

See Get list of event notifications and Get list of subscriptions for more information.

We have made a set of improvements in the BILL webhook notification payloads for consistency with other BILL v3 API responses.

• The createdTime and updatedTime value format is now consistent with the format in other BILL v3 API responses. The format is yyyy-MM-dd'T'HH:mm:ss.SSSX. For example, 2024-12-15T22:53:15.127+00:00.
• In the notification payloads for bills, the invoiceNumber and invoiceDate information is now in the invoice object. This matches the format of the /v3/bills API response.

See Webhooks for more information.

We have introduced a new API endpoint for getting organization price plan details. A BILL price plan for an organization provides a range of information, including monthly subscription fees and the terms and conditions for additional charges in the price plan.

In the Guides section documentation for creating an international vendor, we have added more examples for working with regulatoryFields. We now have examples for Brazil and Australia with instructions for working with regulatoryFields and payment information.

See Creating an international vendor for more information.

We have introduced a set of API endpoints for adding a phone for a user. You can also check whether a phone number has been added for the user. BILL requires users to have a linked phone number for initiating risk verification for an organization.