Bulk payments

Use POST /v3/payments/bulk to pay up to 50 bills with one request. Bulk payments at BILL follow a set of rules.

Successful response: In your bulk payment request, all your bill payments must be successful for a successful response. If any bill payment is not successful, the entire request fails and none of the bills in the request are paid.
You can pay multiple vendors: You can pay multiple vendors with one POST /v3/payments/bulk request. In this case, make sure that you do not set vendorId in your request.
You can only pay existing bills: When you create a single payment with POST /v3/payments, you can set createBill as true in your request for creating a new bill for a vendor payment. In your bulk payment request, an existing billId is required for each bill to be paid.
Vendors with "combinePayments": true: When you create a bulk payment for a vendor that has "combinePayments": true, BILL combines payments for up to 35 bills in one payments response object, and then combines payments for the remaining bills in a second payments response object.

👍
Applying vendor credits
Each payment line in a bulk request must be zero or positive. Do not use negative payment amounts to represent credits. Instead, apply the Vendor Credit to the bill. If the credit fully covers the bill (balance is $0), exclude that bill from the bulk payment request entirely.

NOTE: Each payment line in a bulk request must be zero or positive. Do not use negative payment amounts to represent credits. Instead, apply the Vendor Credit to the bill first. If the credit fully covers the bill (balance is $0), exclude that bill from the bulk payment request entirely.

In your POST /v3/payments/bulk request, set the required fields.

Field	Description
`processDate`	Bill payment processing date in the `yyyy-MM-dd` format. Funds are withdrawn from the sender's funding account on this date. Note: When you add a vendor bank account, BILL requires 2 business days to complete a one-time verification of the bank account. To pay such a vendor, you must set a `processDate` that is at least 2 business days from the current date.
`fundingAccount`	Funding account information. `type` (`BANK_ACCOUNT`, `CARD_ACCOUNT`, or `WALLET` (BILL balance)) `id`: BILL-generated ID of the selected payment funding type. For the `WALLET` type, `id` is not required.
`billId`	BILL-generated ID of the bill to be paid. This value begins with `00n`.
`amount`	Payment amount

See the POST /v3/payments/bulk API for more information about the other bulk payment fields you can set.

Bulk payment to multiple vendors

In this cURL example, a bulk payment is created with two bills that belong to different vendors. The billId is associated with each payment. Funding account details are added to provide a bank account source for the payment.

👍
You can pay a single vendor or multiple vendors
Your POST /v3/payments/bulk request can be the same regardless of whether you are paying a single vendor or multiple vendors.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/payments/bulk' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
    "processDate": "2026-12-16",
    "fundingAccount": {
    	"type": "BANK_ACCOUNT",
    	"id": "{org_bank_account_id}"
  	},
  	"payments": [
    {
      "billId": "{bill_id01}",
      "amount": 228.99
    },
    {
      "billId": "{bill_id02}",
      "amount": 142.00
    }
  ]
}'

Sample response

In this successful response, a different BILL-generated payment id is available for each payment made to each vendor. Each id value begin with stp.

The billPayments object shows that the payment amount is applied to each bill. The bill payment is identified by a bill payment id. This value begins with blp. In addition, disbursement information is available based on the type of payment.

The singleStatus field provides a complete view of your payment based on status and disbursementStatus at different stages of your payment lifecycle. See Single status payment values for more information.

{
  "payments": [
    {
      "id": "stp02TAXHUYITPCGf3b5",
      "vendorId": "{vendor_id01}",
      "billId": "{bill_id01}",
      "billPayments": [
        {
          "id": "{bill_payment_id01}",
          "billId": "{bill_id01}",
          "amount": 228.99
        }
      ],
      "description": "Inv #1216202602",
      "processDate": "2026-12-16",
      "fundingAccount": {
         "type": "BANK_ACCOUNT",
         "id": "{org_bank_account_id}"
      },
      "amount": 228.99,
      "processingOptions": {
        "requestPayFaster": false,
        "requestCheckDeliveryType": "STANDARD"
      },
      "transactionNumber": "EHHXAICWPQDUEIBOEAER",
      "confirmationNumber": "P24121502 - 1389127",
      "status": "SCHEDULED",
      "onlinePayment": true,
      "disbursementType": "CHECK",
      "createdTime": "2026-12-15T20:59:39.816+00:00",
      "updatedTime": "2026-12-15T20:59:40.000+00:00",
      "createdBy": "{user_id}",
      "voidInfo": [],
      "disbursementStatus": "SCHEDULE",
      "singleStatus": "SCHEDULED"
    },
    {
      "id": "stp02TAXHUYITPCGf3b6",
      "vendorId": "{vendor_id02}",
      "billId": "{bill_id02}",
      "billPayments": [
        {
          "id": "{bill_payment_id01}",
          "billId": "{bill_id02}",
          "amount": 142.00
        }
      ],
      "description": "Inv #1216202601",
      "processDate": "2026-12-16",
      "fundingAccount": {
        "type": "BANK_ACCOUNT",
        "id": "{org_bank_account_id}"
      },
      "amount": 142.00,
      "processingOptions": {
        "requestPayFaster": false,
        "requestCheckDeliveryType": "STANDARD"
      },
      "transactionNumber": "EHHXAICWPQDUEIBOEAES",
      "confirmationNumber": "P24121502 - 1389129",
      "status": "SCHEDULED",
      "onlinePayment": true,
      "disbursementType": "CHECK",
      "createdTime": "2026-12-15T20:59:39.816+00:00",
      "updatedTime": "2026-12-15T20:59:40.000+00:00",
      "createdBy": "{user_id}",
      "voidInfo": [],
      "disbursementStatus": "SCHEDULE",
      "singleStatus": "SCHEDULED"
    }
  ]
}

Error response

In the above POST /v3/payments/bulk request, consider an example where the payment amount for the first bill is greater than the $228.99 bill amount. This will result in an error response.

In this error response, there are details about the error at the individual bill level. The entire request fails and none of the bills in the request are paid.

[
    {
        "timestamp": "2026-12-15T20:59:39.816+00:00",
        "code": "BDC_1159",
        "severity": "ERROR",
        "category": "DOWNSTREAM",
        "message": "Cannot overpay a bill."
    },
    {
        "timestamp": "2026-12-15T20:59:39.816+00:00",
        "code": "BDC_1159",
        "severity": "ERROR",
        "category": "DOWNSTREAM",
        "message": "{bill_id01}: Cannot overpay a bill."
    }
]

Combine bulk payments to a single vendor

In the above cURL example, consider that the two bills belong to the same vendor that has combinePayments set as true.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/payments/bulk' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
    "processDate": "2026-12-16",
    "fundingAccount": {
    "type": "BANK_ACCOUNT",
    "id": "{org_bank_account_id}",
    "vendorId": {vendor_id}
  },
  "payments": [
    {
      "billId": "{bill_id01}",
      "amount": 228.99
    },
    {
      "billId": "{bill_id02}",
      "amount": 142.00
    }
  ]
}'

Sample response

In this successful response, one BILL-generated payment id is available for the bulk payment made to the same vendor. This value begin with stp. The bulk payment amount is combined and sent to the vendor.

👍
You can pay vendors regardless of the combinePayments value
If the vendor does not have combinePayments set as true, the POST /v3/payments/bulk response includes a different payment id for each payment made to the vendor. The response looks just like a bulk payments response made to multiple vendors.

{
  "payments": [
    {
      "id": "stp02TAXHUYITPCGf3b5",
      "vendorId": "{vendor_id}",
      "billPayments": [
        {
          "id": "{bill_payment_id01}",
          "billId": "{bill_id01}",
          "amount": 228.99
        },
        {
          "id": "{bill_payment_id02}",
          "billId": "{bill_id02}",
          "amount": 142.00
        }
      ],
      "description": "Multiple inv. (details on stub)",
      "processDate": "2026-12-16",
      "fundingAccount": {
        "type": "BANK_ACCOUNT",
        "id": "{org_bank_account_id}"
      },
      "amount": 370.99,
      "processingOptions": {
        "requestPayFaster": false,
        "requestCheckDeliveryType": "STANDARD"
      },
      "transactionNumber": "EHHXAICWPQDUEIBOEAER",
      "confirmationNumber": "P24121502 - 1389127",
      "status": "SCHEDULED",
      "onlinePayment": true,
      "disbursementType": "CHECK",
      "createdTime": "2026-12-15T20:59:39.816+00:00",
      "updatedTime": "2026-12-15T20:59:40.000+00:00",
      "createdBy": "{user_id}",
      "voidInfo": [],
      "disbursementStatus": "SCHEDULE",
      "singleStatus": "SCHEDULED"
    }
  ]
}

See the POST /v3/payments/bulk API for more information.

Applying vendor credits

Bulk payment to multiple vendors

You can pay a single vendor or multiple vendors

Sample response

Error response

Combine bulk payments to a single vendor

Sample response

You can pay vendors regardless of the combinePayments value

You can pay vendors regardless of the `combinePayments` value