Recurring bills

A recurring bill is a template for creating identical bills for periodic payments to a vendor. Each bill represents an amount owed for goods and services provided by the vendor.

In the recurring bill template, you can add bill line items to record details about individual goods or services. Recurring bill invoice numbers are automatically set as the bill due date in the YYYY-MM-DD format. See the /v3/recurringbills API for more information about the complete list of recurring bill operations.

Creating a recurring bill

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

FieldDescription
vendorIdBILL-generated ID of the vendor you want to pay. This value begins with 009.
scheduleRecurring bills scheduling information.
- period :DAILY, WEEKLY, MONTHLY, or YEARLY
- frequency: Bill frequency per time period. For example, if the time period is MONTHLY and frequency is 3, a bill is generated once every 3 months.
- nextDueDate
- endDate
- daysInAdvance: Number of days before nextDueDate when the next bill is generated. If the date has occurred in the past for one or more bills, all those bills are generated.
recurringBillLineItemsIn the recurringBillLineItems array, set amount as the bill line item amount.

See the /v3/recurringbills API for more information about the other recurring bill fields you can set.

Sample request

In this cURL example, a recurring bill of $19.99 is set up for the vendor (vendorId).

The schedule is once a month for 12 months and each bill is created 5 days before the bill due date. Bank account information is added and auto-pay is enabled for each created bill.

curl --request POST \
--url 'https://gateway.sandbox.bill.com/connect/v3/recurringbills' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "vendorId": "{vendor_id}",
  "schedule": {
    "period": "MONTHLY",
    "frequency": 1,
    "nextDueDate": "2024-12-31",
    "endDate": "2025-11-01",
    "daysInAdvance": 5
  },
  "recurringBillLineItems": [{
    "amount": 19.99,
    "description": "One record per month subscription"
  }],
  "processingOptions": {
    "autoPayment": true
  },
  "paymentInformation": {
    "bankAccountId": "bac01123ABC456DEF789"
  }
}'

Response

In the response, a BILL-generated recurring bill id is available. This value begins with btp. A bill id is generated for each bill created based on the schedule.

{
  "id": "{recurringBill_id}",
  "archived": false,
  "vendorId": "{vendor_id}",
  "schedule": {
    "period": "MONTHLY",
    "frequency": 1,
    "nextDueDate": "2024-12-31",
    "endDate": "2025-11-01",
    "daysInAdvance": 5
  },
  "recurringBillLineItems": [
    {
      "id": "{recurringBillLineItem_id}",
      "amount": 19.99,
      "description": "One record per month subscription"
    }
  ],
  "processingOptions": {
    "autoPayment": true
  },
  "paymentInformation": {
    "bankAccountId": "bac01123ABC456DEF789"
  }
}

See the /v3/recurringbills API for more information about the complete list of recurring bill operations