BILL Spend & Expense API
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. The notification includes the bill id for identifying the bill in your organization. In addition, createdTime provides the created date and time.

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "bill.created",
        "version": "1"
    },
    "bill": {
        "id": "{bill_id}",
        "vendorId": "{vendor_id}",
        "invoice": {
            "invoiceNumber": "202401",
            "invoiceDate": "2024-12-15T00:00:00.000Z"
        },
        "amount": 228.99,
        "createdTime": "2024-12-15T23:15:23.127+00:00",
        "archived": false
    }
}

Sample bill.updated payload

In this sample unescaped JSON payload, the details of an updated bill are available. The notification includes the bill id for identifying the bill in your organization. In addition, updatedTime provides the updated date and time.

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "bill.updated",
        "version": "1"
    },
    "bill": {
        "id": "{bill_id}",
        "invoice": {
            "invoiceNumber": "202402"
        },
        "amount": 230.00,
        "updatedTime": "2024-12-25T23:15:23.127+00:00"
    }
}

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 line item 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 notification provides three bill fields.

FieldDescription
idBILL-generated ID of the bill. The value begins with 00n.
updatedTimeUpdated date and time
archivedSet as true if the bill is archived
{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "bill.archived",
        "version": "1"
    },
    "bill": {
        "id": "{bill_id}",
        "updatedTime": "2024-12-27T23:15:23.127+00:00",
        "archived": true
    }
}

Sample bill.restored payload

In this sample unescaped JSON payload, the details of a restored bill are available. The notification provides three bill fields.

FieldDescription
idBILL-generated ID of the bill. The value begins with 00n.
updatedTimeUpdated date and time
archivedSet as true if the bill is archived
{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "bill.restored",
        "version": "1"
    },
    "bill": {
        "id": "{bill_id}",
        "updatedTime": "2024-12-29T23:15:23.127+00:00",
        "archived": false
    }
}

Updated 29 days ago