In the Spend & Expense Transactions API, we have added syncStatus to the list of transaction filters. In the Get list of transactions (GET /v3/spend/transactions) request, you can now filter transactions with the syncStatus field.
This field provides information about the current sync status of the transaction with your accounting system. The possible syncStatus values are PENDING, SYNCED, ERROR, MANUAL_SYNCED, or NOT_SYNCED.
New field you can filter with | Available operators |
|---|---|
|
|
In the invoices API endpoints, we have introduced the capability of adding convenience fees. In the Create an invoice (POST /v3/invoices), Replace an invoice (PUT /v3/invoices/{invoice_id} ), and Update an invoice (PATCH /v3/invoices/{invoice_id} ) requests, you can now set convenience fees in the convenienceFee object. To set the convenience fee, the new enableCardPayment field must be set as true.
In the convenienceFee object, you can now set a convenience fee percentage that you want to charge your customer when they pay the invoice using a card.
In the invoices API endpoints, we have introduced the capability of adding a sales tax to taxable invoice line items. In the Create an invoice (POST /v3/invoices), Replace an invoice (PUT /v3/invoices/{invoice_id} ), and Update an invoice (PATCH /v3/invoices/{invoice_id} ) requests, you can now set a sales tax with the new salesTaxItemId field.
You can set salesTaxItemId as the BILL-generated ID of the SALES_TAX item. The value begins with 0ii. The tax rate is applied to all the invoice line items set as taxable. You can set up a SALES_TAX percentage item with POST /v3/classifications/items.
In the invoices API endpoints, we have introduced the invoicePdfId field. In all the invoices API responses, you can now get the BILL-generated ID of the invoice PDF.
The invoice PDF is sent as an email attachment when you send an invoice to a customer. The invoice PDF also appears when the customer clicks the invoice payment link to complete the invoice payment.
See POST /v3/invoices in the API reference for more information.
In the attachments API endpoint, we have introduced the replaceInvoicePdf field. In the Upload invoice attachment (POST /v3/attachments/invoices/{invoiceId}) request, you can now set the replaceInvoicePdf field as true to replace the existing invoice PDF with a new PDF attachment.
The invoice PDF is sent as an email attachment when you send an invoice to a customer. The invoice PDF also appears when the customer clicks the invoice payment link to complete the invoice payment.
See POST /v3/attachments/invoices/{invoiceId} in the API reference for more information.
We have introduced a new API endpoint for deleting an attachment.
You can now delete an existing attachment, A deleted attachment cannot be restored. The deleted attachment is not available in the list of attachments.
| Operation | API endpoint |
|---|---|
| Delete an attachment | DELETE /v3/attachments/{attachmentId} |
In the organizations API endpoints, we have introduced the individualTransferOut and individualTransferIn fields. In the Update an organization (PATCH /v3/organizations/{organizationId}) request, you can now set these fields to specify how ACH transfers are made with the organization funding bank account.
Field | Description |
|---|---|
| Rule for how ACH transfers are made from the organization funding bank account to vendors.
|
| Rule for how ACH transfers are made from customers to the organization funding bank account.
|
See PATCH /v3/organizations/{organizationId} in the API reference for more information.
We have introduced a set of API endpoints for bill approvals. With v3 bill approvals, you can now create and manage approval policies for bills based on a set of rules. In an approval policy, the approvers can be individual users or user groups.
When you create or update a bill with the v3 API, set billApprovals as true for BILL to add approvals information in the v3 bills response.
When you have approval policies set up for bills and a bill matches the policy, you now see an additional approvers array of objects in the v3 bills response. The array shows the list of individual users and/or user groups assigned as bill approvers. In addition, the array provides information about the status of the bill in the current approval flow.
For any approvers added to a v3 bill, the approvals must be complete before you can pay the bill with the API.
| Operation | API endpoint |
|---|---|
| Create a bill approval policy | POST /v3/bill-approvals |
| Get list of bill approval policies | GET /v3/bill-approvals/policies |
| Update a bill approval policy | PUT /v3/bill-approvals/policies/{policyId} |
| Delete a bill approval policy | DELETE /v3/bill-approvals/policies/{policyId} |
| Approve or deny a bill | POST /v3/bill-approvals/actions |
| Get list of bills pending approvals | GET /v3/bill-approvals/pending-user-approvals |
See Bill approvals for more information.
We have introduced a new Update an organization price plan (PATCH /v3/partner/organizations/{organization_id}/price-plan) endpoint.
When you onboard as a BILL partner, BILL works with you to set up price plans for the organizations you create. Your organizations can have up to 5 price plans. Each price plan is named in the PricePlanN format (PricePlan1 up to PricePlan5). Use this new endpoint to update the price plan for an existing organization.
See PATCH /v3/partner/organizations/{organizationId}/price-plan in the API reference for more information.
Use BILL webhooks to subscribe to and receive real time notifications for events, such as create a vendor, update a bill, or create a payment. When you get the events catalog and create subscriptions, set the required header values based on the events you want to subscribe to.
| Event | Header values |
|---|---|
| Organization-level AP & AR events | devKey and sessionId |
| Partner-level AP & AR events | appKey and sessionId |
| Spend & Expense events | apiToken |
In your Create a subscription (POST /v3/spend/subscriptions) request, the X-Idempotent-Key header value must be in the UUID4 format. In addition, you can use an online service for generating a test notificationUrl value. For example, webhook.site.
