--- updatedAt: 2026-06-11T23:24:45.000Z agentTools: projectIndex: https://developer.bill.com/llms.txt --- # Bulk payments Use `POST /v3/payments/bulk` to pay up to 50 bills with one API request. See the POST /v3/payments/bulk API for the complete list of available operations. > 👍 Creating a bulk payment is an MFA-trusted operation > > Creating a bulk payment requires an MFA-trusted API session. See MFA setup in the API reference for information about the BILL MFA process. 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. If the funding account type is set as **`WALLET`**, **`processDate`** is required. For other funding account types, if **`processDate`** is not set, the date is automatically set as the next available payment 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. The 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 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. ```json { "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. ```json [ { "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 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. 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. ```json { "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.