---
updatedAt: 2026-03-24T18:41:22.000Z
agentTools:
  projectIndex: https://developer.bill.com/llms.txt
---

# 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 <Anchor label="/v3/recurringbills" target="_blank" href="createrecurringbill">/v3/recurringbills</Anchor> API for the complete list of available operations.

## Create a recurring bill

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

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `vendorId`
      </td>

      <td>
        BILL-generated ID of the vendor you want to pay. This value begins with **`009`**.
      </td>
    </tr>

    <tr>
      <td>
        `schedule`
      </td>

      <td>
        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.
      </td>
    </tr>

    <tr>
      <td>
        `recurringBillLineItems`
      </td>

      <td>
        In the **`recurringBillLineItems`** array, set **`amount`** as the bill line item amount.
      </td>
    </tr>
  </tbody>
</Table>

See the <Anchor label="POST /v3/recurringbills" target="_blank" href="createrecurringbill">POST /v3/recurringbills</Anchor> 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
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": "2026-12-31",
    "endDate": "2026-11-01",
    "daysInAdvance": 5
  },
  "recurringBillLineItems": [{
    "amount": 19.99,
    "description": "Monthly subscription"
  }],
  "processingOptions": {
    "autoPayment": true
  },
  "paymentInformation": {
    "bankAccountId": "{org_bank_account_id}"
  }
}'
```

### 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.

```json
{
  "id": "{recurringBill_id}",
  "archived": false,
  "vendorId": "{vendor_id}",
  "schedule": {
    "period": "MONTHLY",
    "frequency": 1,
    "nextDueDate": "2026-12-31",
    "endDate": "2027-11-01",
    "daysInAdvance": 5
  },
  "recurringBillLineItems": [
    {
      "id": "{recurringBillLineItem_id}",
      "amount": 19.99,
      "description": "Monthly subscription"
    }
  ],
  "processingOptions": {
    "autoPayment": true
  },
  "paymentInformation": {
    "bankAccountId": "{org_bank_account_id}"
  }
}
```

See the <Anchor label="/v3/recurringbills" target="_blank" href="createrecurringbill">/v3/recurringbills</Anchor> API for the complete list of available operations.