Guides
System Status
Start typing to search…

Vendor updated notification payloads

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

👍

Any vendor can be enrolled to accept vendor cards

A vendor can be enrolled to accept virtual card payments even without being connected in the BILL network. In a vendor.created payload, the networkStatus can be NOT_CONNECTED, but the vendor virtual card status can be set as ENROLLED.

See Virtual card FAQ in the BILL Help Center for more information.

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 Connect with a vendor in the BILL Network 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",
        "shortName": "Happy",
        "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 Connect with a vendor in the BILL Network 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",
        "shortName": "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 Connect with a vendor in the BILL Network 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",
        "shortName": "Happy",
        "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.

FieldDescription
idBILL-generated ID of the vendor. The value begins with 009.
paymentInformationPayment type information
updatedTimeUpdated 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",
        "shortName": "Happy",
        "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",
        "shortName": "Happy",
        "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",
        "shortName": "Happy",
        "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",
        "shortName": "Happy",
        "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",
        "shortName": "Happy",
        "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 timeUse 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.

Updated 11 days ago