---
title: "Replace a recurring invoice"
method: PUT
path: "/v3/recurring-invoices/{recurringInvoiceId}"
tags: ["recurring-invoices"]
---

# Replace a recurring invoice

`PUT /v3/recurring-invoices/{recurringInvoiceId}`

Update the number of line items in a recurring invoice. You can also update other recurring invoice details.

You can use the PUT operation to add, remove, or replace the number of line items in a recurring invoice. A set of rules apply with the PUT operation.
* When you add a new line item, a new line item `id` is generated in the invoice.
* When you omit an existing line item `id`, the line item is removed from the invoice.

When a recurring invoice is modified, all future invoices are automatically changed.

## Path parameters

- `recurringInvoiceId` string, required — BILL-generated ID of the recurring invoice. The value begins with `rit`.

## Headers

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

## Request body

- RecurringInvoiceReplaceRequestDto — Replace a recurring invoice (line item added)
  - `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` RecurringInvoiceReplaceLineItem[], required — 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`.
  - `sendEmail` boolean — Set as `true` to send an email to the customer when an invoice is created.

## Response `200`

Replace 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)