July 22nd, 2024

added

New partner features for the BILL webhook API

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.

Partner-level header values for webhooks	Organization-level header values for webhooks
`X-Idempotent-Key` Idempotency key. The key must be in the UUID4 format.	`X-Idempotent-Key` Idempotency key. The key must be in the UUID4 format.
`sessionId` Partner API session ID generated with `/v3/partner/login`	`sessionId` API session ID generated with `/v3/login`
`appKey` Application key sent to you by BILL when you create a partner account	`devKey` Developer key sent to you by BILL when you create a developer account

July 22nd, 2024

added

New v3 API endpoints for MFA

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

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

Operation	API endpoint
Add phone for MFA setup	`POST /v3/mfa/setup`
Validate phone for MFA setup	`POST /v3/mfa/validate`
Generate MFA challenge	`POST /v3/mfa/challenge`
Validate MFA challenge	`POST /v3/mfa/challenge/validate`

July 22nd, 2024

improved

Risk verification decision status update

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.

July 22nd, 2024

improved

Payments API response improvements

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.

June 28th, 2024

improved

List events and subscriptions improvements

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.

June 28th, 2024

improved

Webhook notification payload improvements

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.

June 28th, 2024

added

New v3 API endpoint for getting organization price plan details

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.

Operation	API endpoint
Get organization price plan details	`GET /v3/organizations/{organizationId}/price-plan`

June 28th, 2024

improved

Creating an international vendor documentation improvements

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.

June 28th, 2024

added

New v3 API endpoints for adding phone for risk verification

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.

Operation	API endpoint
Add phone for risk verification	`POST /v3/risk-verifications/phone`
Check phone status for risk verification	`GET /v3/risk-verifications/phone`

June 28th, 2024

improved

Spend & Expense API redesign

We are excited to announce a customer-focused redesign for the Spend & Expense API endpoints. The core of the changes are about further simplifying the /v3/spend/budgets API endpoints. In addition, we have introduced many quality of life updates and simplifications in other Spend & Expense API endpoints.

Our expectations with the redesign are that the terminology and experience will now be closer for customers who are familiar with the web app experience.

Budgets operation updates

New endpoints

Endpoint	Description
`PUT /v3/spend/budgets/{budgetId}/members/bulk`	Update a list of budget members in a budget. For more than 5 users, the request will be processed asynchronously.
`GET /v3/spend/budgets/{budgetId}/members/{userId}`	Get a member in a budget
`PUT /v3/spend/budgets/{budgetId}/members/{userId}`	Update a member in a budget
`DELETE /v3/spend/budgets/{budgetId}/members/{userId}`	Delete a member from a budget

Deleted endpoints

Endpoint
`PATCH /v3/spend/budgets/{budgetId}/userAllocations/{userAllocationId}`
`GET /v3/spend/budgets/{budgetId}/userAllocations/{userAllocationId}`
`PATCH /v3/spend/budgets/{budgetId}/users`

General updates

Change	Description
Renamed	The `periodInterval` field is renamed to `recurringInternal` The `limitless` field is renamed to `limitlessOverspend`
Added	`recurringInterval`: Budget funds reset interval `overspendBuffer`: Amount over the budget limit before transactions are declined
Removed	The `type` field is removed. Use `recurringInterval` instead.

GET /v3/spend/budgets

Change	Description
Added	Sorting and filtering operations are now consistent with other BILL v3 API list operations
Removed	The `type` field is removed. You can continue filtering with this field.

GET /v3/spend/budgets/{budgetId}/members

Change	Description
Renamed	The `GET /v3/spend/budgets/{budgetId}/userAllocations` endpoint is renamed to `GET /v3/spend/budgets/{budgetId}/members`
Added	Sorting and filtering operations are now consistent with other BILL v3 API list operations
Removed	The `retired` field is removed. You can continue filtering with this field.

Cards operation updates

New endpoint

Endpoint	Description
`GET /v3/spend/cards/{cardId}/pan-jwt`	Get a JWT token for retrieving a card's PAN (full account number). The JWT token contains all the information required for retrieving details about a virtual card (16-digit PAN, CVV, and expiration date). The JWT token lifespan is 5 minutes.

Deleted endpoint

Endpoint
`GET /v3/spend/cards/getPanToken/{token}` (See `GET /v3/spend/cards/{cardId}/pan-jwt`)

General updates

Change	Description
Renamed	The `amount` field is renamed to `limit`
Added	The `limit`, `shareBudgetFunds`, and `recurringLimit` fields are moved from the user allocation logic
Removed	The `budgetAllocation` field is removed. You can use `budgetId` for this information. The `isPhysical` field is removed. You can use `type` for this information. The `token` field is removed. See `GET /v3/spend/cards/{cardId}/pan-jwt` for more information.

GET /v3/spend/cards

Change	Description
Added	Sorting and filtering operations are now consistent with other BILL v3 API list operations
Removed	The `userIds` field is removed as a body parameter. You can continue filtering with this field.

PATCH /v3/spend/cards/{cardId}

Change	Description
Added	The user allocation update logic is now a part of `PATCH /v3/spend/cards/{cardId}`

Transactions operation updates

General updates

Change	Description
Renamed	The `receiptSyncStatusType` field is renamed to `receiptSyncStatus`. The `receiptStatusType` field is renamed to `receiptStatus`. The `companyProgramNetworkName` field is renamed to `network`. The `hasAllRequiredFieldsCompleted` field is renamed to `complete`.
Removed	The `cleanedMerchantName` field is removed. You can use `merchantName` for this information. The `declineDetails` field is removed. You can use `declineReason` for this information.

Other updates

All date-time fields are consistent across all BILL v3 API endpoints. For example, deletedAt is renamed to deletedTime.