---
updatedAt: 2026-03-16T21:27:16.000Z
agentTools:
  projectIndex: https://developer.bill.com/llms.txt
---

# AP bill notification payloads

When you subscribe to a BILL event and the event triggers, BILL sends a notification to your provided `notificationUrl`. See <Anchor label="/v3/bills" target="_blank" href="ref:createbill">/v3/bills</Anchor>  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.

```json bill.created JSON payload
{
    "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.

```json bill.updated JSON payload
{
    "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.

| Field                   | Description                                                                                          |
| :---------------------- | :--------------------------------------------------------------------------------------------------- |
| `vendorId`              | BILL-generated ID of the vendor. The value begins with `009`.                                        |
| `amount`                | Bill 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

In this sample unescaped JSON payload, the details of an archived bill are available. The `archived` field is set as `true`.

```json bill.archived JSON payload
{
    "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`.

```json bill.restored JSON payload
{
    "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"
    }
}
```