v1

latestOpenAPI 3.0.12026-07-24310590875.6 KB

payments

Create a bulk payment

Create a request for paying multiple bills. You can pay up to 50 bills with one POST /v3/payments/bulk 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.

See Get list of vendor payment options to get details about vendor payment options and payment process dates.

Note: Creating a bulk payment requires an MFA-trusted API session. See MFA setup for information about the BILL MFA process.

See Payments in the Guides section for more information, sample requests, and responses.

post/v3/payments/bulk

Headers

sessionIdstring nullable

API session ID generated with /v3/login

Example:{{session_id}}

devKeystring nullable

Developer key generated with your BILL developer account

Example:{{developer_key}}

Request body

vendorIdstring

BILL-generated ID of the vendor to be paid. The value begins with 009.

If vendorId is set, it must match each bill’s vendor ID.
Do not set vendorId when you are paying multiple vendors with one request.

descriptionstring

Bill payment description. This value is included in the check memo or in the bank descriptor for electronic payments.

processDatestring date

Payment process date in the yyyy-MM-dd format. On this date, BILL starts processing the payment and starts withdrawing funds from the sender's funding account.

When the vendor bill currency is not USD (For example, EUR), the payment processDate for this vendor must be the next US business day.

If the funding account type is set as WALLET or AP_CARD, processDate is required. For other funding account types, if processDate is not set, the date is automatically set as the next US business day.

Note: When you add a vendor bank account in the production environment, 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 2 business days from the current date.

exchangeRateBatchIdinteger

Exchange rate batch ID. This field is required for paying international vendors when the vendor bill currency is not USD.

Get the current BILL exchange rate and exchange rate batch ID with GET /v3/payments/exchange-rate or POST /v3/payments/exchange-rate (for multiple international vendors).

transactionNumberstring

Payment transaction reference used as an external identifier.

You can set this field as a unique alphanumeric value for your system to track the payment transaction. The value must be 50 characters or fewer. If you do not set transactionNumber, BILL sets this field as a unique alphanumeric payment identification value.

cardFundingPurposestring

Card funding purpose. This field is required for the CARD_ACCOUNT funding account type if BILL cannot identify the vendor industry.

See Get card funding purpose for more information.

Example request

{
  "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
    }
  ]
}

Response

Create a bulk payment response