Guides
System Status

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

In 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}",
        "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

In 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

When changes are made to a set of fields in a bill, the bill.updated event notification is triggered.

FieldDescription
vendorIdBILL-generated ID of the vendor. The value begins with 009.
amountBill amount. For a bill in an international currency (not USD), this value is in the local currency.
paymentStatusBill payment status (PAID, UNPAID, PARTIALLY_PAID, SCHEDULED, IN_PROGRESS, or UNDEFINED)
invoice.invoiceNumberUser-generated invoice number. This value can be your chosen number scheme or bill due date.
invoice.invoiceDateDate when the invoice is sent. This value is in the yyyy-MM-dd format.

Sample bill.archived payload

In 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

In 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 4 days ago