Recurring invoices

A recurring invoice is a template for creating identical invoices for accepting recurring payments from a customer. Each invoice represents an amount that you are owed by a customer for goods and services that your organization provides.

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

Create a recurring invoice

In your POST /v3/recurring-invoices request, set the required fields.

Field	Description
`customerId`	BILL-generated ID of the customer. This value begins with `0cu`.
`schedule`	Recurring invoices scheduling information. - `period` : `DAILY`, `WEEKLY`, `MONTHLY`, or `YEARLY` - `frequency`: Invoice frequency per time `period`. For example, if the time `period` is `MONTHLY` and frequency is `3`, an invoice is generated once every `3` months. - `nextDueDate` - `endDate` - `daysInAdvance`: Number of days before `nextDueDate` when the next invoice is generated. If the date has occurred in the past for one or more invoices, all those invoices are generated.
`recurringInvoiceLineItems`	In the `recurringInvoiceLineItems` array, set `amount` and `quantity`.

See the /v3/recurring-invoices API for more information about the other recurring invoice fields you can set.

Sample request

In this cURL example, a recurring invoice of $19.99 is set up for the customer (customerId). The schedule is once a month for 12 months and each invoice is created 5 days before the invoice due date.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/recurring-invoices' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "customerId": "{customer_id}",
  "schedule": {
    "period": "MONTHLY",
    "frequency": 1,
    "nextDueDate": "2025-12-31",
    "endDate": "2026-11-01",
    "daysInAdvance": 5
  },
  "recurringInvoiceLineItems": [{
    "amount": 19.99,
    "quantity": 1,
    "description": "Monthly subscription"
  }]
}'

Response

In the response, a BILL-generated recurring invoice id is available. This value begins with rit. An invoice id is generated for each invoice created based on the schedule.

{
  "id": "{recurringInvoice_id}",
  "archived": false,
  "customerId": "{customer_id}",
  "schedule": {
    "period": "MONTHLY",
    "frequency": 1,
    "nextDueDate": "2025-12-31",
    "endDate": "2025-11-01",
    "daysInAdvance": 5
  },
  "recurringInvoiceLineItems": [
    {
      "id": "{recurringInvoiceLineItem_id}",
      "amount": 19.99,
      "description": "Monthly subscription"
    }
  ]
}

See the /v3/recurring-invoices API for more information about the complete list of recurring invoice operations.