Vendor updated notification payloads

BILL sends vendor.updated notifications for a set of operations.

Vendor connection updates in the BILL network

BILL sends notifications based on whether a vendor is connected or disconnected in the BILL network.

Vendor connected in the BILL network

In this sample unescaped JSON payload, the details of an updated vendor are available. The notification includes four vendor fields with details about the vendor connection.

Field	Description
`id`	BILL-generated ID of the vendor. The value begins with `009`.
`paymentNetworkId`	Payment Network ID (PNI) of the connected vendor
`networkStatus`	Network connection status. The value is set as `CONNECTED`. See Connecting with a BILL network vendor for more information.
`updatedTime`	Updated date and time

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.updated",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "name": "Happy Music Supplies",
        "archived": false,
        "email": "[email protected]",
        "phone": "9876543210",
        "paymentNetworkId": "{PNI_id}",
        "networkStatus": "CONNECTED",
        "accountNumber": 987000654,
        "address": {
            "line1": "123 Main St",
            "line2": "Suite 200",
            "city": "San Jose",
            "stateOrProvince": "CA",
            "zipOrPostalCode": "95002",
            "country": "US"
        },
        "paymentInformation": {
            "payeeName": "Happy Music Supplies",
            "email": "[email protected]",
            "payByType": "ACH",
            "virtualCard": {
                "status": "UNKNOWN"
            }
        },
        "additionalInfo": {
            "taxId": "9998887777",
            "taxIdType": "SSN",
            "track1099": false,
            "leadTimeInDays": 10,
            "combinePayments": true,
            "companyName": "Happy Music Supplies"
        },
        "recurringPayments": false,
        "billCurrency": "USD",
        "balance": {
            "amount": 0.00
        },
        "autoPay": {
            "enabled": false
        },
        "createdTime": "2025-12-15T22:53:15.127+00:00",
        "updatedTime": "2025-12-16T22:53:15.127+00:00" 
    }
}

Verified national vendor connected

In this sample unescaped JSON payload, the details of an updated vendor are available. The notification includes four vendor fields with details about the vendor connection.

Field	Description
`id`	BILL-generated ID of the vendor. The value begins with `009`.
`rppsId`	Payment Network ID (PNI) of the connected verified national vendor
`networkStatus`	Network connection status. The value is set as `CONNECTED_RPPS`. See Connecting with a BILL network vendor for more information.
`updatedTime`	Updated date and time

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.updated",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "name": "GEICO",
        "archived": false,
        "email": "[email protected]",
        "phone": "9876543210",
        "rppsId": "{PNI_id}",
        "networkStatus": "CONNECTED_RPPS",
        "accountNumber": 987000654,
        "address": {
            "line1": "6220 America Center Drive",
            "city": "San Jose",
            "stateOrProvince": "CA",
            "zipOrPostalCode": "95002",
            "country": "US"
        },
        "paymentInformation": {
            "payeeName": "GEICO",
            "email": "[email protected]",
            "payByType": "RPPS",
            "virtualCard": {
                "status": "UNKNOWN"
            }
        },
        "additionalInfo": {
            "taxId": "9998887777",
            "taxIdType": "SSN",
            "track1099": false,
            "leadTimeInDays": 10,
            "combinePayments": true,
            "companyName": "GEICO"
        },
        "recurringPayments": false,
        "billCurrency": "USD",
        "balance": {
            "amount": 0.00
        },
        "autoPay": {
            "enabled": false
        },
        "createdTime": "2025-12-15T22:53:15.127+00:00",
        "updatedTime": "2025-12-17T22:53:15.127+00:00" 
    }
}

Vendor or verified national vendor disconnected

In this sample unescaped JSON payload, the details of an updated vendor are available. The notification includes three vendor fields with details about the vendor connection.

Field	Description
`id`	BILL-generated ID of the vendor. The value begins with `009`.
`networkStatus`	Network connection status. The value is set as `NOT_CONNECTED`. See Connecting with a BILL network vendor for more information.
`updatedTime`	Updated date and time

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.updated",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "name": "Happy Music Supplies",
        "archived": false,
        "email": "[email protected]",
        "phone": "9876543210",
        "networkStatus": "NOT_CONNECTED",
        "accountNumber": 987000654,
        "address": {
            "line1": "123 Main St",
            "line2": "Suite 200",
            "city": "San Jose",
            "stateOrProvince": "CA",
            "zipOrPostalCode": "95002",
            "country": "US"
        },
        "paymentInformation": {
            "payeeName": "Happy Music Supplies",
            "email": "[email protected]",
            "payByType": "CHECK",
            "virtualCard": {
                "status": "UNKNOWN"
            }
        },
        "additionalInfo": {
            "taxId": "9998887777",
            "taxIdType": "SSN",
            "track1099": false,
            "leadTimeInDays": 10,
            "combinePayments": true,
            "companyName": "Happy Music Supplies"
        },
        "recurringPayments": false,
        "billCurrency": "USD",
        "balance": {
            "amount": 0.00
        },
        "autoPay": {
            "enabled": false
        },
        "createdTime": "2025-12-15T22:53:15.127+00:00",
        "updatedTime": "2025-12-18T22:53:15.127+00:00" 
    }
}

Vendor payment type updates

When the payment method for a vendor is changed, BILL sends notifications based on the updates to the vendor payByType value.

`payByType` changed from `CHECK` to `ACH` or `WALLET`

In this sample unescaped JSON payload, the details of an updated vendor are available. The notification includes three vendor fields with details about the payment information.

Field	Description
`id`	BILL-generated ID of the vendor. The value begins with `009`.
`paymentInformation`	Payment type information
`updatedTime`	Updated date and time

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.updated",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "name": "Happy Music Supplies",
        "archived": false,
        "email": "[email protected]",
        "phone": "9876543210",
        "networkStatus": "NOT_CONNECTED",
        "accountNumber": 987000654,
        "address": {
            "line1": "123 Main St",
            "line2": "Suite 200",
            "city": "San Jose",
            "stateOrProvince": "CA",
            "zipOrPostalCode": "95002",
            "country": "US"
        },
        "paymentInformation": {
            "payeeName": "Happy Music Supplies",
            "email": "[email protected]",
            "lastPaymentDate": "2025-12-18T00:00:00.000+00:00",
            "payByType": "ACH",
            "virtualCard": {
                "status": "UNKNOWN"
            }
        },
        "additionalInfo": {
            "taxId": "9998887777",
            "taxIdType": "SSN",
            "track1099": false,
            "leadTimeInDays": 10,
            "combinePayments": true,
            "companyName": "Happy Music Supplies"
        },
        "recurringPayments": false,
        "billCurrency": "USD",
        "balance": {
            "amount": 0.00,
            "lastUpdatedDate": "2025-12-18T00:00:00.000+00:00"
        },
        "autoPay": {
            "enabled": false
        },
        "createdTime": "2025-12-15T22:53:15.127+00:00",
        "updatedTime": "2025-12-18T00:00:00.000+00:00" 
    }
}

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.updated",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "name": "Happy Music Supplies",
        "archived": false,
        "email": "[email protected]",
        "phone": "9876543210",
        "networkStatus": "NOT_CONNECTED",
        "accountNumber": 987000654,
        "address": {
            "line1": "123 Main St",
            "line2": "Suite 200",
            "city": "San Jose",
            "stateOrProvince": "CA",
            "zipOrPostalCode": "95002",
            "country": "US"
        },
        "paymentInformation": {
            "payeeName": "Happy Music Supplies",
            "email": "[email protected]",
            "lastPaymentDate": "2025-12-19T00:00:00.000+00:00",
            "payByType": "WALLET",
            "virtualCard": {
                "status": "UNKNOWN"
            }
        },
        "additionalInfo": {
            "taxId": "9998887777",
            "taxIdType": "SSN",
            "track1099": false,
            "leadTimeInDays": 10,
            "combinePayments": true,
            "companyName": "Happy Music Supplies"
        },
        "recurringPayments": false,
        "billCurrency": "USD",
        "balance": {
            "amount": 0.00,
            "lastUpdatedDate": "2025-12-19T00:00:00.000+00:00"
        },
        "autoPay": {
            "enabled": false
        },
        "createdTime": "2025-12-15T22:53:15.127+00:00",
        "updatedTime": "2025-12-19T00:00:00.000+00:00" 
    }
}

`payByType` changed from `ACH` or `WALLET` to `CHECK`

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

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.updated",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "name": "Happy Music Supplies",
        "archived": false,
        "email": "[email protected]",
        "phone": "9876543210",
        "networkStatus": "NOT_CONNECTED",
        "accountNumber": 987000654,
        "address": {
            "line1": "123 Main St",
            "line2": "Suite 200",
            "city": "San Jose",
            "stateOrProvince": "CA",
            "zipOrPostalCode": "95002",
            "country": "US"
        },
        "paymentInformation": {
            "payeeName": "Happy Music Supplies",
            "email": "[email protected]",
            "lastPaymentDate": "2025-12-20T00:00:00.000+00:00",
            "payByType": "CHECK",
            "virtualCard": {
                "status": "UNKNOWN"
            }
        },
        "additionalInfo": {
            "taxId": "9998887777",
            "taxIdType": "SSN",
            "track1099": false,
            "leadTimeInDays": 10,
            "combinePayments": true,
            "companyName": "Happy Music Supplies"
        },
        "recurringPayments": false,
        "billCurrency": "USD",
        "balance": {
            "amount": 0.00,
            "lastUpdatedDate": "2025-12-20T00:00:00.000+00:00"
        },
        "autoPay": {
            "enabled": false
        },
        "createdTime": "2025-12-15T22:53:15.127+00:00",
        "updatedTime": "2025-12-20T00:00:00.000+00:00" 
    }
}

`payByType` changed to `VIRTUAL_CARD`

This operation occurs when the vendor is enrolled to accept payments with AP cards. In this sample unescaped JSON payload, the details of an updated vendor are available. The notification includes four vendor fields with details about the payment information.

Field	Description
`id`	BILL-generated ID of the vendor. The value begins with `009`.
`paymentInformation`	Payment type information
`virtualCard`	Virtual card information. - `status`: Enrollment status for the vendor - `remitEmail`: Remittance email address set for the vendor - `enrollDate`: Date when the vendor is enrolled - `alternatePayByType`: Alternate payment method
`updatedTime`	Updated date and time

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.updated",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "name": "Happy Music Supplies",
        "archived": false,
        "email": "[email protected]",
        "phone": "9876543210",
        "networkStatus": "NOT_CONNECTED",
        "accountNumber": 987000654,
        "address": {
            "line1": "123 Main St",
            "line2": "Suite 200",
            "city": "San Jose",
            "stateOrProvince": "CA",
            "zipOrPostalCode": "95002",
            "country": "US"
        },
        "paymentInformation": {
            "payeeName": "Happy Music Supplies",
            "email": "[email protected]",
            "lastPaymentDate": "2025-12-22T00:00:00.000+00:00",
            "payByType": "VIRTUAL_CARD",
            "virtualCard": {
                "status": "ENROLLED",
                "remitEmail": "{remittance_email_address}",
                "enrollDate": "2025-12-21T22:53:15.127+00:00",
                "alternatePayByType": "CHECK"
            }
        },
        "additionalInfo": {
            "taxId": "9998887777",
            "taxIdType": "SSN",
            "track1099": false,
            "leadTimeInDays": 10,
            "combinePayments": true,
            "companyName": "Happy Music Supplies"
        },
        "recurringPayments": false,
        "billCurrency": "USD",
        "balance": {
            "amount": 0.00,
            "lastUpdatedDate": "2025-12-22T00:00:00.000+00:00"
        },
        "autoPay": {
            "enabled": false
        },
        "createdTime": "2025-12-15T22:53:15.127+00:00",
        "updatedTime": "2025-12-22T00:00:00.000+00:00" 
    }
}

`payByType` changed from `VIRTUAL_CARD` to another payment type

This operation occurs when the vendor is unenrolled or declined to accept payments with AP cards. In this sample unescaped JSON payload, the details of an updated vendor are available. The notification includes four vendor fields with details about the payment information.

Field	Description
`id`	BILL-generated ID of the vendor. The value begins with `009`.
`paymentInformation`	Payment type information
`virtualCard`	Virtual card information. - `status`: Enrollment status for the vendor - `declineDate`: Date when the vendor is unenrolled or declined
`updatedTime`	Updated date and time

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.updated",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "name": "Happy Music Supplies",
        "archived": false,
        "email": "[email protected]",
        "phone": "9876543210",
        "networkStatus": "NOT_CONNECTED",
        "accountNumber": 987000654,
        "address": {
            "line1": "123 Main St",
            "line2": "Suite 200",
            "city": "San Jose",
            "stateOrProvince": "CA",
            "zipOrPostalCode": "95002",
            "country": "US"
        },
        "paymentInformation": {
            "payeeName": "Happy Music Supplies",
            "email": "[email protected]",
            "lastPaymentDate": "2025-12-22T00:00:00.000+00:00",
            "payByType": "CHECK",
            "virtualCard": {
                "status": "DECLINED",
                "declineDate": "2025-12-23T22:55:01.127+00:00"
            }
        },
        "additionalInfo": {
            "taxId": "9998887777",
            "taxIdType": "SSN",
            "track1099": false,
            "leadTimeInDays": 10,
            "combinePayments": true,
            "companyName": "Happy Music Supplies"
        },
        "recurringPayments": false,
        "billCurrency": "USD",
        "balance": {
            "amount": 0.00,
            "lastUpdatedDate": "2025-12-22T00:00:00.000+00:00"
        },
        "autoPay": {
            "enabled": false
        },
        "createdTime": "2025-12-15T22:53:15.127+00:00",
        "updatedTime": "2025-12-23T22:53:15.127+00:00" 
    }
}

Complete list of fields that trigger `vendor.updated` notifications

BILL sends vendor.updated notifications when changes are made to a set of fields for a vendor. This list includes the network connection and payment type operations.

Field	Description
`name`	Vendor name
`email`	Vendor email address
`phone`	Vendor phone number
`paymentNetworkId`	Payment Network ID (PNI) of the connected vendor. This field is available only when a vendor is connected in the BILL network.
`rppsId`	Payment Network ID (PNI) of the connected verified national vendor. This field is available only when a verified national vendor is connected.
`networkStatus`	Network connection status (`NOT_CONNECTED`, `PENDING`, `CONNECTED`, or `CONNECTED_RPPS`). This field is available only when a network connection status is available for the vendor. See Vendor connection updates in the BILL network for information about `vendor.updated` notifications for `paymentNetworkId`, `rppsId`, and `networkStatus` updates.
`accountNumber`	User account number set by the vendor
`address`	Vendor address information. - `line1`: Address line 1 - `line2`: Address line 2 - `city`: Address city - `stateOrProvince`: State or province - `zipOrPostalCode`: Zip or postal code - `country`: Country code (ISO2)
`paymentInformation`	Vendor payment information. - `payeeName`: Vendor name for check and electronic payments - `email`: Vendor email address for receiving payment information - `lastPaymentDate`: Last payment date. This field is available only when a vendor payment is made. - `payByType`: Payment method for BILL payments - `virtualCard`: Virtual card informationSee Vendor payment type updates for information about `vendor.updated` notifications for `paymentType` and `virtualCard` updates.
`additionalInfo`	Vendor additional information. - `taxId`: Vendor tax ID. This value is required by the IRS for tax purposes. - `taxIdType`: Vendor tax ID type - `track1099`: Set as `true` if the vendor is eligible to receive an IRS form 1099 from the payer - `leadTimeInDays`: Vendor payment lead time in days - `combinePayments`: Set as `true` if multiple bills with the same processing date are combined into one payment to the vendor. The default value is `true`. - `companyName`: Vendor business name. This value is required by the IRS for tax purposes.
`balance`	Vendor account balance information. These fields are updated for a set of use cases. - `amount`: Balance amount to be paid to the vendor - `lastUpdatedDate`: Balance amount last updated date and time Use cases for updates to the `balance` fields. - When a vendor payment is made - When a bill for the vendor is created, updated, archived, or restored
`autoPay`	Vendor auto-pay information. The `enabled` field is set as `true` if vendor auto-pay is enabled.

Vendor connection updates in the BILL network

Vendor connected in the BILL network

Verified national vendor connected

Vendor or verified national vendor disconnected

Vendor payment type updates

payByType changed from CHECK to ACH or WALLET

payByType changed from ACH or WALLET to CHECK

payByType changed to VIRTUAL_CARD

payByType changed from VIRTUAL_CARD to another payment type

Complete list of fields that trigger vendor.updated notifications

`payByType` changed from `CHECK` to `ACH` or `WALLET`

`payByType` changed from `ACH` or `WALLET` to `CHECK`

`payByType` changed to `VIRTUAL_CARD`

`payByType` changed from `VIRTUAL_CARD` to another payment type

Complete list of fields that trigger `vendor.updated` notifications