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.
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.
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.
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}/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.
In the Guides section documentation for creating an international vendor, we learned that there was a need for further explaining the use of paymentPurpose and regulatoryFields. These objects are required in your request for enabling payments to international vendors.
We have updated the documentation with examples of international vendor locations like Brazil and Austria with instructions for setting paymentPurpose and regulatoryFields.
In the payment webhook notification payload, you now receive descriptive status and type names instead of a numeric code. The payment status, funding account type, and disbursement type values have been updated.
We have introduced a set of document and attachment API endpoints. You can now upload documents for bills with the v3 API. In addition, you can upload supporting attachments for vendors, customers, and invoices.
The BILL partner API endpoints require sessionId as a header value that is generated with API partner login (POST /v3/partner/login). We learned that API login as user (POST /v3/partner/login-as-user) endpoint is the only BILL partner endpoint where sessionId is required as a body parameter.
For consistency across the BILL partner API endpoints, we now require sessionId as a header value for the API login as user endpoint. See API login as user in the API reference for more information.
