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.

Field	Description
`vendorId`	BILL-generated ID of the vendor you want to pay. This value begins with `009`.
`schedule`	Recurring 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.
`recurringBillLineItems`	In 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.stage.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