Guides
System Status
Start typing to search…

AP 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": "625947c4-8e6b-48f0-ae72-ea9c9375ec27",
        "subscriptionId": "f6d06930-e3e2-4509-be37-4dbda29efc6i",
        "organizationId": "00802DEVKGROHKDIY4zyx",
        "eventType": "bill.created",
        "version": "1"
    },
    "bill": {
        "id": "00n02JZNIEYMNPY99iz9",
        "vendorId": "00902BILKFECNEV2oji1",
        "invoice": {
            "invoiceNumber": "202601",
            "invoiceDate": "2026-12-15T00:00:00.000Z"
        },
        "amount": 228.99,
        "createdTime": "2026-12-15T23:15:23.127+00:00",
        "updatedTime": "2026-12-15T23:15:23.127+00:00",
        "createdBy": "00602NNWYXSZQYLTa41g",
        "archived": false,
        "description": "Happy Music Supplies Dec Bill",
        "dueDate": "2026-12-31",
        "paymentStatus": "UNPAID",
        "payFromChartOfAccountId": "0ca02GRSNLIBIMWStq9t",
        "classifications":{
            "chartOfAccountId": "0ca02WKKWLSRRCFItdlc",
            "accountingClassId": "cls02MAWJVVFXUGRcomq",
            "departmentId": "0de02KKZIBYGPDVTewla",
            "locationId": "loc02GTGYTKLKDINc1qa"
        },
        "purchaseOrderNumber": "po-123"
    }
}

Sample bill.updated payload

In this sample unescaped JSON payload, the details of an updated bill are available.

{
    "metadata": {
        "eventId": "625947c4-8e6b-48f0-ae72-ea9c9375ec27",
        "subscriptionId": "f6d06930-e3e2-4509-be37-4dbda29efc6i",
        "organizationId": "00802DEVKGROHKDIY4zyx",
        "eventType": "bill.updated",
        "version": "1"
    },
    "bill": {
        "id": "00n02JZNIEYMNPY99iz9",
        "vendorId": "00902BILKFECNEV2oji1",
        "vendorName": "Happy Music Supplies",
        "invoice": {
            "invoiceNumber": "202602",
            "invoiceDate": "2026-12-15T00:00:00.000Z"
        },
        "amount": 230.00,
        "createdTime": "2026-12-15T23:15:23.127+00:00",
        "updatedTime": "2026-12-25T23:15:23.127+00:00",
        "createdBy": "00602NNWYXSZQYLTa41g",
        "archived": false,
        "description": "Happy Music Supplies Dec Bill",
        "dueDate": "2026-12-31",
        "paymentStatus": "UNPAID",
        "payFromChartOfAccountId": "0ca02GRSNLIBIMWStq9t",
        "classifications":{
            "chartOfAccountId": "0ca02WKKWLSRRCFItdlc",
            "accountingClassId": "cls02MAWJVVFXUGRcomq",
            "departmentId": "0de02KKZIBYGPDVTewla",
            "locationId": "loc02GTGYTKLKDINc1qa"
        },
        "purchaseOrderNumber": "po-123"
    }
}

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.
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": "625947c4-8e6b-48f0-ae72-ea9c9375ec27",
        "subscriptionId": "f6d06930-e3e2-4509-be37-4dbda29efc6i",
        "organizationId": "00802DEVKGROHKDIY4zyx",
        "eventType": "bill.archived",
        "version": "1"
    },
    "bill": {
        "id": "00n02JZNIEYMNPY99iz9",
        "vendorId": "00n02JZNIEYMNPY99iz9",
        "vendorName": "Happy Music Supplies",
        "invoice": {
            "invoiceNumber": "202602",
            "invoiceDate": "2026-12-15T00:00:00.000Z"
        },
        "amount": 230.00,
        "createdTime": "2026-12-15T23:15:23.127+00:00",
        "updatedTime": "2026-12-27T23:15:23.127+00:00",
        "createdBy": "00602NNWYXSZQYLTa41g",
        "archived": true,
        "description": "Happy Music Supplies Dec Bill",
        "dueDate": "2026-12-31",
        "paymentStatus": "UNPAID",
        "payFromChartOfAccountId": "0ca02GRSNLIBIMWStq9t",
        "classifications":{
            "chartOfAccountId": "0ca02WKKWLSRRCFItdlc",
            "accountingClassId": "cls02MAWJVVFXUGRcomq",
            "departmentId": "0de02KKZIBYGPDVTewla",
            "locationId": "loc02GTGYTKLKDINc1qa"
        },
        "purchaseOrderNumber": "po-123"
    }
}

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": "625947c4-8e6b-48f0-ae72-ea9c9375ec27",
        "subscriptionId": "f6d06930-e3e2-4509-be37-4dbda29efc6i",
        "organizationId": "00802DEVKGROHKDIY4zyx",
        "eventType": "bill.restored",
        "version": "1"
    },
    "bill": {
        "id": "00n02JZNIEYMNPY99iz9",
        "vendorId": "00902BILKFECNEV2oji1",
        "vendorName": "Happy Music Supplies",
        "invoice": {
            "invoiceNumber": "202602",
            "invoiceDate": "2026-12-15T00:00:00.000Z"
        },
        "amount": 230.00,
        "createdTime": "2026-12-15T23:15:23.127+00:00",
        "updatedTime": "2026-12-29T23:15:23.127+00:00",
        "createdBy": "00602NNWYXSZQYLTa41g",
        "archived": false,
        "description": "Happy Music Supplies Dec Bill",
        "dueDate": "2026-12-31",
        "paymentStatus": "UNPAID",
        "payFromChartOfAccountId": "0ca02GRSNLIBIMWStq9t",
        "classifications":{
            "chartOfAccountId": "0ca02WKKWLSRRCFItdlc",
            "accountingClassId": "cls02MAWJVVFXUGRcomq",
            "departmentId": "0de02KKZIBYGPDVTewla",
            "locationId": "loc02GTGYTKLKDINc1qa"
        },
        "purchaseOrderNumber": "po-123"
    }
}

Updated 20 days ago