Batch Changed

batch-changed tells you that a batch's settings were updated.

When it fires

Only when the batch itself is updated with Patch Batch or from the dashboard: for example its name, reference ID, archive flag, allowed payout methods or denied countries.

It does not fire when payments are added, paid or cancelled, even though the batch's counts and totals change. Follow those with the payment events, or read the batch with Get Batch.

What to do

Compare auditInfo.updatedAt with the copy you hold, and keep the newer one.
If deniedCountries changed, expect payments to payees in those countries to become RESTRICTED.

Payload

data is the batch as Get Batch describes it, read when the webhook is sent. Fields with no value are omitted. Amounts use the Money object. Totals are arrays with one entry per currency in the batch, and an empty array when there is nothing to count.

Field	Type	Description
`id`	string	Batch ID.
`payorId`	string	Your payor ID.
`referenceId`	string	Your own reference for the batch.
`name`	string	Batch name, shown to you and to payees, for example `Weekly payroll`.
`taxJurisdiction`	string	Tax rules applied to the batch's payments: `us`, `de`, `fi`, `gb`, `my`, `pl`, `sa`, `se`, or `none`.
`defaultPaymentCategory`	string	Category given to new payments that do not set one. One of `online-esport-prize`, `in-person-esport-prize`, `in-person-esport-prize-out-of-jurisdiction`, `athlete-prize`, `online-misc-prize`, `online-contest-prize`, `in-person-misc-prize`, `in-person-contest-prize`, `remote-contractors`, `in-person-contractors`, `reimbursement`, `royalties`.
`archived`	boolean	`true` if the batch is archived.
`allowedPaymentMethods`	string[]	Payout methods payees may use for this batch's payments, for example `bank-transfer-1`. Absent when every method enabled for your account is allowed.
`deniedCountries`	string[]	Two-letter ISO country codes of payees this batch must not pay. Payments to them become `RESTRICTED`.
`onboarded`	number	Share of the batch's payments whose payee is payable, from `0` to `1`.
`numberOfPayments`	number	Payments in the batch.
`numberOfPaidPayments`	number	Payments that have been paid.
`numberOfUnpaidPayments`	number	Payments not yet paid.
`numberOfPayableNowPayments`	number	Payments you can submit now.
`numberOfCancelledPayments`	number	Payments that were cancelled.
`totalAmount`	Money[]	Total of all payments, excluding cancelled ones.
`totalPaid`	Money[]	Total already paid.
`totalUnpaid`	Money[]	Total not yet paid.
`totalPayableNow`	Money[]	Total you can submit now.
`totalCancelled`	Money[]	Total of cancelled payments.
`paymentsSummary`	object	The same counts and totals grouped by state. Has `total`, `paid`, `unpaid`, `payableNow` and `cancelled`, each with `amount` (Money[]), `count` (number) and `byCurrency` (array of `{currency, totalAmount, count}`), plus `onboardedPercentage` (number, `0` to `1`).
`auditInfo`	object	`createdAt`, `updatedAt` (ISO 8601 UTC), `createdBy` and `updatedBy`.

Counts and totals are recalculated in the background as payments change. They do not fire this event themselves, so the figures in a delivery are only as current as the moment it was sent. Use Get Batch for current figures.

Example

The full request body Payment Labs sends:

{
  "payorId": "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
  "event": "batch-changed",
  "timestamp": "2026-03-15T10:12:40.087Z",
  "data": {
    "archived": false,
    "payorId": "C-01JBX2Q8F4H6K8M0N2P4R6T8VW",
    "id": "B-01JC8Z1B2C3D4E5F6G7H8J9K0M",
    "name": "March tournament prizes (final)",
    "referenceId": "payrun-2026-03",
    "taxJurisdiction": "us",
    "defaultPaymentCategory": "online-esport-prize",
    "auditInfo": {
      "createdAt": "2026-03-14T13:55:02.000Z",
      "updatedAt": "2026-03-15T10:12:39.511Z",
      "createdBy": "[email protected]",
      "updatedBy": "[email protected]"
    },
    "allowedPaymentMethods": [
      "bank-transfer-1",
      "paypal"
    ],
    "deniedCountries": [
      "KP"
    ],
    "numberOfPayments": 3,
    "numberOfPaidPayments": 1,
    "numberOfUnpaidPayments": 2,
    "numberOfPayableNowPayments": 1,
    "numberOfCancelledPayments": 0,
    "onboarded": 0.6666666666666666,
    "totalAmount": [
      {
        "value": 4750,
        "wholeValue": 475000,
        "currency": "USD",
        "formattedValue": "$4,750.00",
        "digits": 2
      }
    ],
    "totalPaid": [
      {
        "value": 1250,
        "wholeValue": 125000,
        "currency": "USD",
        "formattedValue": "$1,250.00",
        "digits": 2
      }
    ],
    "totalCancelled": [],
    "totalUnpaid": [
      {
        "value": 3500,
        "wholeValue": 350000,
        "currency": "USD",
        "formattedValue": "$3,500.00",
        "digits": 2
      }
    ],
    "totalPayableNow": [
      {
        "value": 2000,
        "wholeValue": 200000,
        "currency": "USD",
        "formattedValue": "$2,000.00",
        "digits": 2
      }
    ]
  }
}