Vendor notification payloads

When you subscribe to a BILL event and the event triggers, BILL sends a notification to your provided notificationUrl. See /v3/vendors in the API reference for more information about the request and response fields.

Sample `vendor.created` payload

In this sample unescaped JSON payload, the details of a created vendor are available. The notification includes the vendor id for identifying the vendor in your organization. In addition, createdTime provides the created date and time. All the fields are included in each vendor.created payload.

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.created",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "name": "{vendor_name}",
        "address" : {
          "country": "US"
        }, 
        "createdTime": "2025-12-15T22:53:15.127+00:00",
        "archived": false
    }
}

Sample `vendor.updated` payloads

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

Vendor name or address country is updated

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

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.updated",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "name": "{vendor_name}",
        "updatedTime": "2025-12-16T23:15:15.127+00:00"
    }
}

Vendor connected in the BILL network

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

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. 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}",
        "paymentNetworkId": "{PNI_id}",
        "networkStatus": "CONNECTED",
        "updatedTime": "2025-12-20T22:55:15.127+00:00"
    }
}

Verified national vendor connected

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

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. 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}",  
        "rppsId": "{PNI_id}",  
        "networkStatus": "CONNECTED_RPPS",  
        "updatedTime": "2025-02-21T22:55:01.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 provides three vendor fields.

Field	Description
`id`	BILL-generated ID of the vendor. The value begins with `009`.
`networkStatus`	Network connection status. 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}",
        "networkStatus": "NOT_CONNECTED",
        "updatedTime": "2025-12-21T22:55:01.127+00:00"
    }
}

Sample `vendor.archived` payload

In this sample unescaped JSON payload, the details of an archived vendor are available. The notification provides three vendor fields.

Field	Description
`id`	BILL-generated ID of the vendor. The value begins with `009`.
`updatedTime`	Updated date and time
`archived`	Set as `true` if the vendor is archived

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.archived",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "updatedTime": "2025-02-25T22:55:01.127+00:00",
        "archived": true
    }
}

Sample `vendor.restored` payload

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

Field	Description
`id`	BILL-generated ID of the vendor. The value begins with `009`.
`updatedTime`	Updated date and time
`archived`	Set as `true` if the vendor is archived

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.restored",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "updatedTime": "2025-02-30T22:55:01.127+00:00",
        "archived": false
    }
}

Sample vendor.created payload

Sample vendor.updated payloads