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.

Idempotency key and notification URL for creating subscriptions

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.

Helpful links

• See BILL v3 API Postman collection for more information about working with the Postman collection.
• See Webhooks in the Guides section for more information about working with BILL Webhooks.

On October 17, 2025, we will release Bill Approvals in the BILL v3 API. With this release, approvals information will automatically be added to bills created with the v3 API.

What's New

When we release bill approvals in the BILL v3 API, approvals information will automatically be added to bills created with the v3 API. If you have approval policies set up for bills using the BILL web app, you will now see an additional approvers array of objects in the v3 bills response.

For example, if your bill approval policy requires approval for all bills greater than or equal to $1000, a bill created with amount set as 1500.00 will include a list of assigned approvers in the v3 bills response.

{
  "id": "{bill_id}",
  "archived": false,
  "vendorId": "{vendor_id}",
  "amount": 1500.00,
  "dueDate": "2025-12-31",
  "invoice": {
    "invoiceNumber": "202501",
    "invoiceDate": "2025-12-31"
  },
  "billLineItems": [
    {
      "id": "{billLineItem_id01}",
      "amount": 1500.00
    }
  ],
  "paymentStatus": "UNPAID",
  "approvalStatus": "ASSIGNED",
  "createdTime": "2025-12-30T23:15:23.127+00:00",
  "updatedTime": "2025-12-30T23:15:23.127+00:00",
  "approvers": [
    {
      "userId": "{user_id}",
      "status": "WAITING",
      "approverOrder": 0,
      "statusChangedTime": "2025-12-30T23:15:23.127+00:00"
    }
  ]
}

In this sample response, the approvers array shows the current user assigned as an approver for the bill. In addition, status is set as WAITING to state that BILL is waiting for the user to perform an approval action on the bill. If there are multiple approvers assigned in an approval policy, each user is listed in an object, and approverOrder provides the order in which bill approvals are required.

Developer Actions

In your integrations,

• If you create a bill with POST /v3/bills or POST /v3/bills/bulk, and
• Pay the bill with POST /v3/payments or POST /v3/payments/bulk,

👉 Make sure that any bill approvals are complete before paying any bill with the API.

👉 Ensure that you handle the added approvers object in the v3 bills response in the production environment.

We have introduced a new feature for accepting or rejecting a Spend & Expense transaction in response to a 3D Secure challenge triggered to verify the identity of the cardholder.

New webhook for 3D Secure challenges

We have updated the webhooks events catalog to include the spend.three-ds-challenge.created event. Notifications are triggered for this event when a 3D Secure challenge is triggered for a Spend & Expense transaction. You can now set up subscriptions to receive notifications for the new event.

See Spend & Expense 3D Secure challenge notification payload for more information.

New v3 API endpoint for responding to 3D Secure challenges

We have a new API endpoint for responding to 3D Secure challenges for Spend & Expense transactions. With the Accept or reject a transaction (POST /v3/spend/transactions/{acsTransactionId}/3ds-challenge) request, you can respond to a webhook notification you receive when a 3D Secure challenge is generated for a transaction.

See Accept or reject a transaction in the API reference for more information.

The BILL v3 API Postman collection is another way for you to test with the BILL v3 API. Simply fork the collection from the Postman API Network and begin testing with different BILL v3 API workflows.

See BILL v3 API Postman collection for more information.

In the Record AP payment endpoint, we have introduced the capability of adding vendor credits. In the Record AP payment (POST /v3/bills/record-payment) request, you can now add vendor credits in the vendorCredits object.

See POST /v3/bills/record-payment in the API reference for more information.

In the bills API endpoints, we have introduced the purchaseOrderNumber field. You can now set this field as a purchase order number linked with the bill.

See POST /v3/bills in the API reference for more information.

Vendor notifications

The vendor webhook notifications now include the shortName field. This field is the vendor short name. When you receive notifications for the vendor.created, vendor.updated, vendor.archived, or vendor.restored events, the notifications now include the shortName field.

See Vendor notification payloads for more information.

Bill notifications

The bill webhook notifications now include the purchaseOrderNumber field. This field is the purchase order number linked with the bill. When you receive notifications for the bill.created, bill.updated, bill.archived, or bill.restored events, the notifications now include the purchaseOrderNumber field.

See Bill notification payloads for more information.

In February 2025, BILL introduced UUIDs in the Spend & Expense API for further improving its security standards. All API responses include both id and uuid values.

As of July 9, 2025, the Spend & Expense id values are being deprecated. Both id and uuid values will continue to be available in all API responses. We strongly recommend that you use uuid instead of id in all your Spend & Expense API operations.

Webhooks Time To Live (TTL)

BILL maintains an event history for each subscription. We have now upgraded the webhooks TTL from 90 days to 180 days. You can get the list of event notifications sent to you for a subscription with GET /v3/events/subscription/{subscription_id}. You can now get the list of events for the last 180 days.

See Webhook API notification rules for more information about the complete set of rules.

Get list of event notifications improvements

We have added the capability for filtering event notifications by an entity ID. For example, to get notifications for a specific bill, you can now filter with the ID of the bill.

In the Get list of event notifications (GET /v3/events/subscription/{subscription_id}) request, you can now filter event notifications with the entityId field.

See GET /v3/events/subscription/{subscriptionId} in the API reference for more information.

We have introduced a set of API endpoints for getting billing statement information for an organization. BILL generates a monthly billing invoice statement for all the billing activities in the organization.

See Organization billing statements for more information.