Bill notification payloads
When you subscribe to a BILL event and the event triggers, BILL sends a notification to your provided notificationUrl
. See /v3/bills in the API reference for more information about the request and response fields.
Sample bill.created
payload
bill.created
payloadIn this sample unescaped JSON payload, the details of a created bill are available.
{
"metadata": {
"eventId": "{event_id}",
"subscriptionId": "{subscription_id}",
"organizationId": "{organization_id}",
"eventType": "bill.created",
"version": "1"
},
"bill": {
"id": "{bill_id}",
"vendorId": "{vendor_id}",
"vendorName": "Happy Music Supplies",
"invoice": {
"invoiceNumber": "202501",
"invoiceDate": "2025-12-15T00:00:00.000Z"
},
"amount": 228.99,
"createdTime": "2025-12-15T23:15:23.127+00:00",
"updatedTime": "2025-12-15T23:15:23.127+00:00",
"archived": false,
"description": "Happy Music Supplies Dec Bill",
"dueDate": "2025-12-31",
"paymentStatus": "UNPAID",
"payFromChartOfAccountId": "{pay_from_chart_of_accounts_id}",
"classifications":{
"chartOfAccountId": "{chart_of_accounts_id}",
"accountingClassId": "{accounting_class_id}",
"departmentId": "{department_id}",
"locationId": "{location_id}"
}
}
}
Sample bill.updated
payload
bill.updated
payloadIn this sample unescaped JSON payload, the details of an updated bill are available.
{
"metadata": {
"eventId": "{event_id}",
"subscriptionId": "{subscription_id}",
"organizationId": "{organization_id}",
"eventType": "bill.updated",
"version": "1"
},
"bill": {
"id": "{bill_id}",
"vendorId": "{vendor_id}",
"vendorName": "Happy Music Supplies",
"invoice": {
"invoiceNumber": "202502",
"invoiceDate": "2025-12-15T00:00:00.000Z"
},
"amount": 230.00,
"createdTime": "2025-12-15T23:15:23.127+00:00",
"updatedTime": "2025-12-25T23:15:23.127+00:00",
"archived": false,
"description": "Happy Music Supplies Dec Bill",
"dueDate": "2025-12-31",
"paymentStatus": "UNPAID",
"payFromChartOfAccountId": "{pay_from_chart_of_accounts_id}",
"classifications":{
"chartOfAccountId": "{chart_of_accounts_id}",
"accountingClassId": "{accounting_class_id}",
"departmentId": "{department_id}",
"locationId": "{location_id}"
}
}
}
Fields that trigger bill.updated
notifications
bill.updated
notificationsWhen changes are made to a set of fields in a bill, the bill.updated
event notification is triggered.
Field | Description |
---|---|
vendorId | BILL-generated ID of the vendor. The value begins with 009 . |
amount | Bill line item amount. For a bill in an international currency (not USD), this value is in the local currency. |
invoice.invoiceNumber | User-generated invoice number. This value can be your chosen number scheme or bill due date. |
invoice.invoiceDate | Date when the invoice is sent. This value is in the yyyy-MM-dd format. |
Sample bill.archived
payload
bill.archived
payloadIn this sample unescaped JSON payload, the details of an archived bill are available. The archived
field is set as true
.
{
"metadata": {
"eventId": "{event_id}",
"subscriptionId": "{subscription_id}",
"organizationId": "{organization_id}",
"eventType": "bill.archived",
"version": "1"
},
"bill": {
"id": "{bill_id}",
"vendorId": "{vendor_id}",
"vendorName": "Happy Music Supplies",
"invoice": {
"invoiceNumber": "202502",
"invoiceDate": "2025-12-15T00:00:00.000Z"
},
"amount": 230.00,
"createdTime": "2025-12-15T23:15:23.127+00:00",
"updatedTime": "2025-12-27T23:15:23.127+00:00",
"archived": true,
"description": "Happy Music Supplies Dec Bill",
"dueDate": "2025-12-31",
"paymentStatus": "UNPAID",
"payFromChartOfAccountId": "{pay_from_chart_of_accounts_id}",
"classifications":{
"chartOfAccountId": "{chart_of_accounts_id}",
"accountingClassId": "{accounting_class_id}",
"departmentId": "{department_id}",
"locationId": "{location_id}"
}
}
}
Sample bill.restored
payload
bill.restored
payloadIn this sample unescaped JSON payload, the details of a restored bill are available. The archived
field is set as false
.
{
"metadata": {
"eventId": "{event_id}",
"subscriptionId": "{subscription_id}",
"organizationId": "{organization_id}",
"eventType": "bill.restored",
"version": "1"
},
"bill": {
"id": "{bill_id}",
"vendorId": "{vendor_id}",
"vendorName": "Happy Music Supplies",
"invoice": {
"invoiceNumber": "202502",
"invoiceDate": "2025-12-15T00:00:00.000Z"
},
"amount": 230.00,
"createdTime": "2025-12-15T23:15:23.127+00:00",
"updatedTime": "2025-12-29T23:15:23.127+00:00",
"archived": false,
"description": "Happy Music Supplies Dec Bill",
"dueDate": "2025-12-31",
"paymentStatus": "UNPAID",
"payFromChartOfAccountId": "{pay_from_chart_of_accounts_id}",
"classifications":{
"chartOfAccountId": "{chart_of_accounts_id}",
"accountingClassId": "{accounting_class_id}",
"departmentId": "{department_id}",
"locationId": "{location_id}"
}
}
}
Updated 5 days ago