AP mass payment notification payloads

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

Sample `mass-payment.updated` payloads

The unescaped JSON payload provides a set of mass-payment fields.

👍
You get mass-payment.updated notifications when the batchStatus changes
When a mass payment is created, BILL sends you mass-payment.updated notifications when the payment batchStatus value changes.

Field	Description
`paymentBatchId`	BILL-generated ID of the mass payment batch. The value begins with `bbq`.
`batchStatus`	Mass payment batch status (`SCHEDULED` or `COMPLETED`)
`count`	Count of the payments based on the current status of each payment in the mass payment batch. `scheduled`: Scheduled payments. For each payment in the list, BILL has not started generating a payment `id` value and API response. `failed`: Failed payments `completed`: Completed payments. For each payment in the list, BILL has successfully generated a payment `id` value and API response. `total`: Total number of payments in the mass payment batch
`updatedTime`	Updated date and time. This is the time when `batchStatus` is updated

When a mass payment is created

In this sample unescaped JSON payload, the details of an AP mass payment batch are available. When a mass payment is created, a mass payment batch ID is available. In addition, batchStatus is set as SCHEDULED. All other fields are included in the mass-payment.updated payload.

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "mass-payment.updated",
        "version": "1"
    },
    "mass-payment": {
        "paymentBatchId": "{mass_payment_batch_id}",
        "batchStatus": "SCHEDULED",
        "count": {
          "scheduled": 3,
          "failed": 0,
          "completed": 0,
          "total": 3
        },
        "updatedTime": "2026-12-16T23:56:52.127+00:00"
    }
}

👍
Subscribe to mass-payment.updated and payment.updated for notifications in the payment lifecycle
When you subscribe to mass-payment.updated, you get notifications about updates in the mass payment batch. When BILL has successfully generated a payment id value and API response for each valid payment in the batch, the batchStatus is set as COMPLETED.
Your payment.updated subscription gives you notifications after the mass payment batch is complete. When BILL begins processing each payment based on the payment processDate, you start receiving payment.updated notifications for each payment.
See AP payment notification payloads in the Guides section to learn about the sample AP payment notification payloads and different payment status values.

When there is an update in the mass payment batch

When BILL has successfully generated a payment id value and API response for each valid payment in the batch, the count information is updated. The count includes the number of all completed and failed payments in the batch.

In addition, batchStatus is set as COMPLETED. All other fields are included in the mass-payment.updated payload.

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "mass-payment.updated",
        "version": "1"
    },
    "mass-payment": {
        "paymentBatchId": "{mass_payment_batch_id}",
        "batchStatus": "COMPLETED",
        "count": {
          "scheduled": 0,
          "failed": 1,
          "completed": 2,
          "total": 3
        },
        "updatedTime": "2026-12-17T23:56:52.127+00:00"
    }
}

Updated about 1 hour ago

Did this page help you?