---
title: "Create a recurring invoice"
method: POST
path: "/v3/recurring-invoices"
tags: ["recurring-invoices"]
---

# Create a recurring invoice

`POST /v3/recurring-invoices`

Create a recurring invoice.

See [Recurring invoices](https://developer.bill.com/docs/ar-recurring-invoices) in the Guides section for more information, sample requests, and responses.

## Headers

- `sessionId` string, nullable — API session ID generated with `/v3/login`
- `devKey` string, nullable — Developer key generated with your BILL developer account

## Request body

- CreateRecurringInvoiceRequestDto — Create a recurring invoice
  - `customerId` string, required — BILL-generated ID of the customer. The value begins with `0cu`.
  - `paymentTermId` string
  - `description` string — User-generated invoice number. This value can be your chosen number scheme or invoice due date.
  - `schedule` object, required — Recurring invoice scheduling information
    - `period` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY' | 'NONE' — Time period for setting up recurring invoices
    - `frequency` integer — 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` string, date — Due date for the next invoice. This value is in the `yyyy-MM-dd` format.
    - `endDate` string, date — End date for the recurring invoices schedule. Recurring invoices stop on the `endDate`. This value is in the `yyyy-MM-dd` format.
    - `daysInAdvance` integer — 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` RecurringInvoiceLineItemDto[], required — Recurring invoice line item information
    - `amount` number — Recurring invoice line item amount. For a recurring invoice in an international currency (not USD), this value is in the local currency.
    - `description` string — Recurring invoice line item description
    - `price` number — Recurring invoice line item unit price. For a recurring invoice in an international currency (not USD), this value is in the local currency.
    - `quantity` number — Recurring invoice line item unit quantity
    - `classifications` object — General ledger classifications information for the recurring invoice line item
      - `chartOfAccountId` string — BILL-generated ID of the chart of accounts. The value begins with `0ca`.
      - `accountingClassId` string — BILL-generated ID of the accounting class. The value begins with `cls`.
      - `departmentId` string — BILL-generated ID of the department. The value begins with `0de`.
      - `jobId` string — BILL-generated ID of the job. The value begins with `job`.
      - `locationId` string — BILL-generated ID of the location. The value begins with `loc`.
      - `itemId` string — BILL-generated ID of the item. The value begins with `0ii`.
  - `sendEmail` boolean — Set as `true` to send an email to the customer when an invoice is created.

## Response `201`

Create a recurring invoice response

- RecurringInvoiceResponseDto — RecurringInvoice response Dto.
  - `id` string, required — BILL-generated ID of the recurring invoice. The value begins with `rit`.
  - `customerId` string — BILL-generated ID of the customer. The value begins with `0cu`.
  - `paymentTermId` string
  - `description` string — Recurring invoice line item description
  - `archived` boolean — Set as `true` if the recurring invoice is archived
  - `schedule` object — Recurring invoice scheduling information
    - `period` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY' | 'NONE' | 'UNDEFINED' — Time period for setting up recurring invoices.
    - `frequency` integer — 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` string, date — Due date for the next invoice. This value is in the `yyyy-MM-dd` format.
    - `endDate` string, date — End date for the recurring invoices schedule. Recurring invoices stop on the `endDate`. This value is in the `yyyy-MM-dd` format.
    - `daysInAdvance` integer — 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` RecurringInvoiceLineItemResponseDto[] — Recurring invoice line item information
    - `id` string — BILL-generated ID of the recurring invoice line item. The value begins with `ril`.
    - `amount` number — Recurring invoice line item amount. For a recurring invoice in an international currency (not USD), this value is in the local currency.
    - `description` string — Recurring invoice line item description
    - `price` number — Recurring invoice line item unit price. For a recurring invoice in an international currency (not USD), this value is in the local currency.
    - `quantity` number — Recurring invoice line item unit quantity
    - `classifications` object — General ledger classifications information for the recurring invoice line item
      - `chartOfAccountId` string — BILL-generated ID of the chart of accounts. The value begins with `0ca`.
      - `accountingClassId` string — BILL-generated ID of the accounting class. The value begins with `cls`.
      - `departmentId` string — BILL-generated ID of the department. The value begins with `0de`.
      - `jobId` string — BILL-generated ID of the job. The value begins with `job`.
      - `locationId` string — BILL-generated ID of the location. The value begins with `loc`.
      - `itemId` string — BILL-generated ID of the item. The value begins with `0ii`.
    - `taxable` boolean — Set as `true` if the recurring invoice line item is taxable
  - `classifications` object — General ledger classifications information for the recurring invoice line item
    - `accountingClassId` string — BILL-generated ID of the accounting class. The value begins with `cls`.
    - `departmentId` string — BILL-generated ID of the department. The value begins with `0de`.
    - `jobId` string — BILL-generated ID of the job. The value begins with `job`.
    - `locationId` string — BILL-generated ID of the location. The value begins with `loc`.
  - `sendEmail` boolean — Set as `true` to send an email to the customer when an invoice is created.
  - `createdTime` string, date-time — Created date and time
  - `updatedTime` string, date-time — Updated date and time

## Other responses

- `4XX` — List of errors.
- `5XX` — List of errors.

---

[API](https://skmtc.net/bill/apis/bill-v3-api.md) · [All operations](https://skmtc.net/bill/apis/bill-v3-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bill/bill-v3-api/revisions/0483350c434e/schema)