---
updatedAt: 2026-04-21T17:39:49.000Z
agentTools:
  projectIndex: https://developer.bill.com/v2/llms.txt
---

# Pay a vendor with BILL

Pay a vendor with BILL for one or more bills. You can also pay multiple vendors with a single `/v2/PayBills.json` request. The maximum number of bills that can be paid with one `/v2/PayBills.json` request is 200.

If you are applying bill credits to a bill, set the bill `amount` as (bill `amount` + bill credit `amount`).

See [Payables payment timing](https://help.bill.com/hc/en-us/articles/115005322726) in the BILL Help Center to learn about the standard BILL payment process and timing.

### Prerequisites
There are two prerequisites for using `/v2/PayBills.json`.
* This is an MFA protected endpoint. Create an MFA-protected API session with `/v2/Login.json` before using `/v2/PayBills.json`.
* The user paying a bill must have either the `Administrator`, `Payer`, or another user role profile that has the permission to pay bills.

### Combining payments made to the same vendor
You can combine payments for multiple bills to the same vendor into one payment if you pay from a bank account.

Ensure that you set `enableCombinePayments` as `true` for the vendor (with `/v2/Crud/Create/Vendor.json` or `/v2/Crud/Updated/Vendor.json`) before paying for multiple bills as one combined payment.

**Note**: With a combined payment, the bill payments have the same process date and are scheduled to be paid at the same time.

### Paying multiple vendors with a single request
There are two requirements for paying multiple vendors with a single `/v2/PayBills.json` request.
* List all the bills for all vendors in the `billPays` array. Set `billId` and `amount` for each bill in the `billPays` array.
* Do not set the `vendorId`. The `vendorId` is automatically set for each bill to be paid.

See [Pay vendors with BILL](doc:paying-vendors-with-bill) in the Guides section for more information, sample requests, and responses, including paying vendors with BILL Pay Faster.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "AP | Vendor transactions",
    "version": "2.0",
    "description": "BILL is a cloud-based cash flow management system for an organization's Accounts Payable (AP) and Accounts Receivable (AR) automation.\n * **AP**: Automate workflows to pay vendors bills at scale for the goods and services they provide. Pay vendors with a wide range of payment methods. Generate vendor credits, bill credits, and payment disbursement reports.\n * **AR**: Automate workflows to get paid by customers at scale for the goods and services you provide. Generate and send invoices on a schedule, generate customer and invoice credits, and seamlessly charge authorized customers.\n * **Organization**: Manage your bank accounts (for sending and receiving payments), users (with user roles), and sync with your choice of accounting software.\n\nIntegrate with the BILL API to send and receive payments for your business. See [Support Center](https://help.bill.com/hc/en-us) for resources about using the BILL web app.",
    "contact": {
      "email": "developerprogram@hq.bill.com"
    }
  },
  "servers": [
    {
      "url": "https://api-stage.bill.com/api/v2",
      "description": "Sandbox base URL"
    }
  ],
  "x-readme": {
    "samples-languages": [
      "curl",
      "java",
      "javascript",
      "python",
      "ruby"
    ]
  },
  "paths": {
    "/PayBills.json": {
      "post": {
        "summary": "Pay a vendor with BILL",
        "operationId": "ap-vendortransactions-paybills",
        "description": "Pay a vendor with BILL for one or more bills. You can also pay multiple vendors with a single `/v2/PayBills.json` request. The maximum number of bills that can be paid with one `/v2/PayBills.json` request is 200.\n\nIf you are applying bill credits to a bill, set the bill `amount` as (bill `amount` + bill credit `amount`).\n\nSee [Payables payment timing](https://help.bill.com/hc/en-us/articles/115005322726) in the BILL Help Center to learn about the standard BILL payment process and timing.\n\n### Prerequisites\nThere are two prerequisites for using `/v2/PayBills.json`.\n* This is an MFA protected endpoint. Create an MFA-protected API session with `/v2/Login.json` before using `/v2/PayBills.json`.\n* The user paying a bill must have either the `Administrator`, `Payer`, or another user role profile that has the permission to pay bills.\n\n### Combining payments made to the same vendor\nYou can combine payments for multiple bills to the same vendor into one payment if you pay from a bank account.\n\nEnsure that you set `enableCombinePayments` as `true` for the vendor (with `/v2/Crud/Create/Vendor.json` or `/v2/Crud/Updated/Vendor.json`) before paying for multiple bills as one combined payment.\n\n**Note**: With a combined payment, the bill payments have the same process date and are scheduled to be paid at the same time.\n\n### Paying multiple vendors with a single request\nThere are two requirements for paying multiple vendors with a single `/v2/PayBills.json` request.\n* List all the bills for all vendors in the `billPays` array. Set `billId` and `amount` for each bill in the `billPays` array.\n* Do not set the `vendorId`. The `vendorId` is automatically set for each bill to be paid.\n\nSee [Pay vendors with BILL](doc:paying-vendors-with-bill) in the Guides section for more information, sample requests, and responses, including paying vendors with BILL Pay Faster.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PayBillsResponse"
                }
              }
            }
          }
        },
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "devKey",
                  "sessionId",
                  "data"
                ],
                "properties": {
                  "devKey": {
                    "type": "string",
                    "description": "Developer key generated with your BILL developer account"
                  },
                  "sessionId": {
                    "type": "string",
                    "description": "API session ID generated with [`/v2/Login.json`](ref:auth-login)"
                  },
                  "data": {
                    "$ref": "#/components/schemas/PayBillsRequest"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "AP transactions"
        ]
      },
      "parameters": []
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error_code": {
            "type": "string",
            "description": "Error code (only when `response_status` is `1`)"
          },
          "error_message": {
            "type": "string",
            "description": "Error message (only when `response_status` is `1`)"
          }
        }
      },
      "PayBillsRequest": {
        "type": "object",
        "required": [
          "billPays"
        ],
        "properties": {
          "vendorId": {
            "type": "string",
            "description": "BILL-generated ID of the vendor to be paid. The value begins with `009`.\n\nIf `vendorId` is set, it must match your bill’s vendor ID. If `vendorId` is not set, the `vendorId` is automatically set for each bill to be paid."
          },
          "bankAccountId": {
            "type": "string",
            "description": "BILL-generated ID of the bank account used to make the bill payment. The value begins with `bac`. If the `bankAccountId` is not set, the organization’s primary bank account is used."
          },
          "cardAccountId": {
            "type": "string",
            "description": "BILL-generated ID of the card account used to make the bill payment. The value begins with `cat`.\n\nThis field is required for paying with a debit card or credit card. You can retrieve this value with `/v2/List/CardAccount.json`."
          },
          "cardFundingPurpose": {
            "type": "string",
            "description": "Card funding purpose. This field is required for paying with a debit card or credit card. You can set this value as any user-defined text."
          },
          "processDate": {
            "type": "string",
            "description": "Bill payment processing date in the YYYY-MM-DD format. Funds are withdrawn from the bank account on this date. If `processDate` is not set, the default value is the next available payment date."
          },
          "description": {
            "type": "string",
            "description": "Bill payment description. This value is included in the check memo or in the bank descriptor for ePayment."
          },
          "isVendorDirectPayment": {
            "type": "boolean",
            "description": "Set as `true` if the bill payment is a virtual card (Vendor Direct) payment"
          },
          "isFasterPayment": {
            "type": "boolean",
            "description": "Set as `true` if the bill payment is eligible for faster payment.\n\nSee [Pay Faster and other expedited payment methods](https://help.bill.com/hc/en-us/articles/115005467886-Pay-bills-using-Pay-Faster) in the BILL Help Center for more information."
          },
          "deliveryType": {
            "type": "string",
            "description": "Check delivery method.\n* `0`: Standard\n* `1`: USPS priority\n* `10`: UPS 1 day delivery\n* `11`: UPS 2 day delivery\n* `12`: UPS 3 day delivery\n* `13`: RTP (Real-Time Payment) delivery"
          },
          "batchId": {
            "type": "integer",
            "description": "Exchange rate batch ID for paying an international vendor. This field is required for making an ePayment to an international vendor."
          },
          "allowExport": {
            "type": "boolean",
            "description": "Set as `true` to mark the payment for sync with your choice of accounting software"
          },
          "billPays": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "billId",
                "amount"
              ],
              "properties": {
                "billId": {
                  "type": "string",
                  "description": "BILL-generated ID of the bill to be paid. The value begins with `00n`."
                },
                "amount": {
                  "type": "number",
                  "description": "Bill amount to be paid. If you are applying bill credits to a bill, the bill `amount` is (bill `amount` + bill credit `amount`)."
                },
                "paymentPurpose": {
                  "type": "string",
                  "description": "Bill payment purpose. Set this field as `SALA` (salary) for a payroll payment.\n\nSee [NACHA Payroll Indicator Frequently Asked Questions (FAQ)](https://help.bill.com/direct/s/article/000004719) for more information.",
                  "enum": [
                    "SALA"
                  ]
                }
              }
            }
          },
          "billCredits": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "billId",
                "amount"
              ],
              "properties": {
                "billId": {
                  "type": "string",
                  "description": "BILL-generated ID of the bill to apply vendor credits. The value begins with 00n`."
                },
                "vendorCreditId": {
                  "type": "string",
                  "description": "BILL-generated ID of the vendor credit. The value begins with `vcr`."
                },
                "amount": {
                  "type": "number",
                  "description": "Vendor credit amount"
                }
              }
            }
          }
        }
      },
      "PayBillsResponse": {
        "type": "object",
        "properties": {
          "response_status": {
            "type": "integer",
            "description": "Response status.\n* `0`: Success response\n* `1`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_message": {
            "type": "string",
            "description": "Response status.\n* `Success`: Success response\n* `Error`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_data": {
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            ],
            "properties": {
              "sentPays": {
                "type": "array",
                "description": "The `SentPay` object records the total bill amount, bill credits, vendor credits, and any remaining bill amount paid.",
                "items": {
                  "type": "object",
                  "properties": {
                    "entity": {
                      "type": "string",
                      "description": "Object type. Set as `SentPay`."
                    },
                    "id": {
                      "type": "string",
                      "description": "BILL-generated ID of the `SentPay` object. The value begins with `stp`."
                    },
                    "processDate": {
                      "type": "string",
                      "description": "Bill payment processing date in the YYYY-MM-DD format. Funds are withdrawn from the bank account on this date. If `processDate` is not set, the default value is the next available payment date."
                    },
                    "amount": {
                      "type": "number",
                      "description": "Payment total amount"
                    },
                    "status": {
                      "type": "string",
                      "description": "Payment status.\n* `0`: Approving\n* `1`: Scheduled\n* `2`: Paid\n* `3`: Canceled\n* `4`: Void\n* `5`: Escheated (Check only)"
                    },
                    "description": {
                      "type": "string",
                      "description": "Payment description.\n* Payments received with BILL (online): Payment description automatically generated by BILL (read-only)\n* Payments received outside BILL (offline): Payment description manually set"
                    },
                    "txnNumber": {
                      "type": "string",
                      "description": "BILL-generated payment identification number"
                    },
                    "name": {
                      "type": "string",
                      "description": "BILL-generated bill payment confirmation number"
                    },
                    "vendorId": {
                      "type": "string",
                      "description": "BILL-generated ID of the vendor. The value begins with `009`."
                    },
                    "isOnline": {
                      "type": "boolean",
                      "description": "Payment source.\n* `true`: Payment is made with BILL (online)\n* `false`: Payment is made outside BILL and then recorded in BILL (offline)"
                    },
                    "fasterPayment": {
                      "type": "boolean",
                      "description": "Set as `true` if the bill payment is eligible for faster payment.\n\nSee [Pay Faster and other expedited payment methods](https://help.bill.com/hc/en-us/articles/115005467886-Pay-bills-using-Pay-Faster) in the BILL Help Center for more information."
                    },
                    "paymentType": {
                      "type": "string",
                      "description": "Payment type.\n* `0`: ACH\n* `1`: Wallet\n* `2`: Card\n* `3`: Wire\n* `9`: Other"
                    },
                    "deliveryTypeRequested": {
                      "type": "string",
                      "description": "Check delivery method.\n* `0`: Standard\n* `1`: USPS priority\n* `10`: UPS 1 day delivery\n* `11`: UPS 2 day delivery\n* `12`: UPS 3 day delivery\n* `13`: RTP (Real-Time Payment) delivery"
                    },
                    "chartOfAccountId": {
                      "type": "string",
                      "description": "BILL-generated ID of the chart of accounts associated with the bill payment. This is an accounts tracking object.\n* Payments made with BILL (online): Automatically set to the BILL money out clearing account (read-only) \n* Payment made outside BILL (offline): You can set the chart of accounts ID"
                    },
                    "syncReference": {
                      "type": "string",
                      "description": "Payment reference ID, such as check number, that you can sync with your choice of accounting software. Use this field only for payments made outside BILL."
                    },
                    "toPrintCheck": {
                      "type": "boolean",
                      "description": "Set as `true` if the check is marked as printable when synced with your choice of accounting software. Use this field only for payments made outside BILL."
                    },
                    "createdTime": {
                      "type": "string",
                      "description": "Created date and time"
                    },
                    "updatedTime": {
                      "type": "string",
                      "description": "Updated date and time"
                    },
                    "createdBy": {
                      "type": "string",
                      "description": "BILL-generated ID of the user that created the payment. This value begins with `006`."
                    },
                    "bankAccountId": {
                      "type": "string",
                      "description": "BILL-generated ID of the bank account used to make the bill payment. If the `bankAccountId` is not set, the organization’s primary bank account is used."
                    },
                    "pt14CardId": {
                      "type": "string",
                      "description": "This field is available only for select BILL partners"
                    },
                    "needAttnReviewed": {
                      "type": "boolean",
                      "description": "Set as `true` if the payment requires approval"
                    },
                    "simpleBasicAutoCancel": {
                      "type": "string",
                      "description": "This field is available only for select BILL partners"
                    },
                    "source": {
                      "type": "string",
                      "description": "`SentPay` source.\n* `0`: BILL\n* `1`: Bill autopay\n* `2`: NetSync from online payment\n* `3`: NetSync from offline payment\n* `4`: eBill autopay\n* `5`: eBill\n* `6`: Recurring payment"
                    },
                    "allowExport": {
                      "type": "boolean",
                      "description": "Set as `true` to mark the payment for sync with your choice of accounting software"
                    },
                    "localAmount": {
                      "type": "string",
                      "description": "Total bill amount paid in local currency"
                    },
                    "exchangeRate": {
                      "type": "number",
                      "description": "Exchange rate for paying an international vendor. This value is required during bill creation and payments to international vendors."
                    },
                    "paymentPurpose": {
                      "type": "string",
                      "description": "Payment purpose"
                    },
                    "remittanceEmail": {
                      "type": "string",
                      "description": "Remittance email address set for the vendor"
                    },
                    "requestedDeliveryDate": {
                      "type": "string",
                      "description": "Requested payment delivery date set by the vendor"
                    },
                    "pmtCurrencyInfoId": {
                      "type": "string",
                      "description": "Payment currency information"
                    },
                    "cardAccountId": {
                      "type": "string",
                      "description": "BILL-generated ID of the card account used to make the bill payment"
                    },
                    "creditAccountId": {
                      "type": "string",
                      "description": "BILL-generated ID of the credit account used to make the bill payment"
                    },
                    "fundsHeldDate": {
                      "type": "string",
                      "description": "Date when the payment funds are held by BILL. Payment funds can be held when the receiver has not accepted the funds in BILL or when the receiver’s bank account has not been set up in BILL."
                    },
                    "fundingType": {
                      "type": "string",
                      "description": "Payment funding type.\n* `0`: Check\n* `1`: ACH to Verified national vendor\n* `2`: ACH\n* `3`: PayPal\n* `4`: Credit card\n* `5`: International ePayment\n* `6`: American Express\n* `7`: Virtual card (Vendor Direct)\n* `8`: Real-time payment\n* `9`: Instant Transfer (Wallet)\n* `10`: Debit card"
                    },
                    "billPays": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "entity": {
                            "type": "string",
                            "description": "Object type. Set as `billPay`."
                          },
                          "id": {
                            "type": "string",
                            "description": "BILL-generated ID of the `billPay` object. The value begins with `blp`."
                          },
                          "billId": {
                            "type": "string",
                            "description": "BILL-generated ID of the bill to the paid. The value begins with `00n`."
                          },
                          "name": {
                            "type": "string",
                            "description": "Bill payment confirmation number automatically generated by BILL"
                          },
                          "paymentStatus": {
                            "type": "string",
                            "description": "Payment status.\n* `1`: Scheduled\n* `2`: Paid\n* `3`: Canceled\n* `4`: Void"
                          },
                          "amount": {
                            "type": "number",
                            "description": "Bill payment total amount"
                          },
                          "description": {
                            "type": "string",
                            "description": "Bill payment description automatically generated by BILL"
                          },
                          "processDate": {
                            "type": "string",
                            "description": "Bill payment processing date in the YYYY-MM-DD format. Funds are withdrawn from the bank account on this date. If `processDate` is not set, the default value is the next available payment date."
                          },
                          "createdTime": {
                            "type": "string",
                            "description": "Created date and time"
                          },
                          "updatedTime": {
                            "type": "string",
                            "description": "Updated date and time"
                          },
                          "paymentType": {
                            "type": "string",
                            "description": "`billPay` payment type.\n* `0`: Online\n* `1`: Other"
                          },
                          "syncReference": {
                            "type": "string",
                            "description": "Payment reference ID, such as check number, that you can sync with your choice of accounting software. Use this field only for payment made outside BILL."
                          },
                          "toPrintCheck": {
                            "type": "boolean",
                            "description": "Set as `true` if the check is marked as printable when synced with your choice of accounting software. Use this field only for payment made outside BILL."
                          },
                          "chartOfAccountId": {
                            "type": "string",
                            "description": "BILL-generated ID of the chart of accounts associated with the bill payment. This is an accounts tracking object.\n* Payments made with BILL (online): Automatically set to the BILL money out clearing account (read-only) \n* Payment made outside BILL (offline): You can set the chart of accounts ID"
                          },
                          "sentPayId": {
                            "type": "string",
                            "description": "BILL-generated ID of the `SentPay` object. The value begins with `stp`."
                          },
                          "allowExport": {
                            "type": "boolean",
                            "description": "Set as `true` to mark the bill payment for sync with your choice of accounting software"
                          },
                          "paymentPurpose": {
                            "type": "string",
                            "description": "Bill payment purpose. This field is set as `PAYROLL` for a payroll payment."
                          }
                        }
                      }
                    },
                    "billCredits": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "entity": {
                            "type": "string",
                            "description": "Object type. Set as `BillCredit`."
                          },
                          "id": {
                            "type": "string",
                            "description": "BILL-generated ID of the bill credit. The value begins with `bcr`."
                          },
                          "billId": {
                            "type": "string",
                            "description": "BILL-generated ID of the bill to apply vendor credits. The value begins with `00n`."
                          },
                          "sentPayId": {
                            "type": "string",
                            "description": "BILL-generated ID of the `SentPay` object. The value begins with `stp`."
                          },
                          "vendorCreditId": {
                            "type": "string",
                            "description": "BILL-generated ID of the vendor credit. The value begins with `vcr`."
                          },
                          "amount": {
                            "type": "string",
                            "description": "Vendor credit amount"
                          },
                          "createdTime": {
                            "type": "string",
                            "description": "Created date and time"
                          },
                          "updatedTime": {
                            "type": "string",
                            "description": "Updated date and time"
                          }
                        }
                      }
                    },
                    "apConvFee": {
                      "type": "object",
                      "properties": {
                        "entity": {
                          "type": "string",
                          "description": "Object type. Set as `APConvFee`."
                        },
                        "id": {
                          "type": "string",
                          "description": "BILL-generated ID of the `APConvFee` object. The value begins with `apf`."
                        },
                        "createdTime": {
                          "type": "string",
                          "description": "Created date and time"
                        },
                        "refNumber": {
                          "type": "string",
                          "description": "BILL-generated unique reference number"
                        },
                        "amount": {
                          "type": "number",
                          "description": "AP convenience fee amount"
                        },
                        "paymentDate": {
                          "type": "string",
                          "description": "Payment creation date"
                        },
                        "chartOfAccountId": {
                          "type": "string",
                          "description": "BILL-generated ID of the chart of accounts associated with the bill payment. This is an accounts tracking object.\n* Payments made with BILL (online): Automatically set to the BILL money out clearing account (read-only) \n* Payment made outside BILL (offline): Chart of accounts ID set by the user"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```