---
updatedAt: 2026-05-27T16:52:24.000Z
agentTools:
  projectIndex: https://developer.bill.com/llms.txt
---

# Replace a recurring invoice

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.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "BILL v3 API",
    "description": "BILL is a cloud-based financial operations platform for an organization's accounts payable (AP), accounts receivable (AR), and spend & expense (S&E) automation.\n\nThe BILL v3 API gives you access to the same infrastructure that powers the AP, AR, and S&E products. In addition, you can receive real-time event notifications with webhooks.\n\nThe BILL Developer Documentation is available at [developer.bill.com](https://developer.bill.com/docs/home).\n\n## Quickstart\nSign-up and generate a developer key for working with the BILL v3 API. With this key, you can build with the AP, AR, BILL network, and webhook workflows. See [Sandbox API sign up](https://developer.bill.com/docs/api-sandbox-sign-up) for more information.\n\n### Spend & Expense API\nAn API token is required for working with the Spend & Expense API. See [Authentication with Spend & Expense API token](https://developer.bill.com/docs/authentication-with-api-token) for more information.\n\n### BILL v3 API in Postman\nWith this collection, you have access to the BILL v3 API in Postman. When you save your sandbox API credentials as environment variables in Postman, you can simply refer to the variables when you are testing with the BILL v3 API. See [BILL v3 API in Postman](https://developer.bill.com/docs/bill-v3-api-in-postman) for more information.",
    "version": "1"
  },
  "servers": [
    {
      "url": "https://gateway.stage.bill.com/connect",
      "description": "sandbox"
    }
  ],
  "paths": {
    "/v3/recurring-invoices/{recurringInvoiceId}": {
      "put": {
        "tags": [
          "recurring-invoices"
        ],
        "summary": "Replace a recurring invoice",
        "description": "Update the number of line items in a recurring invoice. You can also update other recurring invoice details.\n\nYou 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.\n* When you add a new line item, a new line item `id` is generated in the invoice.\n* When you omit an existing line item `id`, the line item is removed from the invoice.\n\nWhen a recurring invoice is modified, all future invoices are automatically changed.",
        "operationId": "replaceRecurringInvoice",
        "parameters": [
          {
            "name": "sessionId",
            "in": "header",
            "schema": {
              "type": "string",
              "description": "API session ID generated with `/v3/login`",
              "nullable": true,
              "example": "{{session_id}}"
            }
          },
          {
            "name": "devKey",
            "in": "header",
            "schema": {
              "type": "string",
              "description": "Developer key generated with your BILL developer account",
              "nullable": true,
              "example": "{{developer_key}}"
            }
          },
          {
            "name": "recurringInvoiceId",
            "in": "path",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string",
              "description": "BILL-generated ID of the recurring invoice. The value begins with `rit`.",
              "example": "{{recurring_invoice_id}}"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecurringInvoiceReplaceRequestDto"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Replace a recurring invoice response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecurringInvoiceResponseDto"
                }
              }
            }
          },
          "4XX": {
            "description": "List of errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/BdcError"
                  }
                }
              }
            }
          },
          "5XX": {
            "description": "List of errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/BdcError"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BdcError": {
        "required": [
          "category",
          "code",
          "severity",
          "timestamp"
        ],
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "code": {
            "type": "string"
          },
          "severity": {
            "$ref": "#/components/schemas/Severity"
          },
          "category": {
            "$ref": "#/components/schemas/Category"
          },
          "message": {
            "type": "string"
          },
          "params": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Param"
            }
          },
          "detail": {
            "type": "string"
          },
          "help": {
            "type": "string"
          }
        }
      },
      "Category": {
        "type": "string",
        "enum": [
          "REQUEST",
          "APPLICATION",
          "SERVER",
          "DOWNSTREAM"
        ]
      },
      "InvoiceClassificationsDto": {
        "type": "object",
        "properties": {
          "accountingClassId": {
            "type": "string",
            "description": "BILL-generated ID of the accounting class. The value begins with `cls`."
          },
          "departmentId": {
            "type": "string",
            "description": "BILL-generated ID of the department. The value begins with `0de`."
          },
          "jobId": {
            "type": "string",
            "description": "BILL-generated ID of the job. The value begins with `job`."
          },
          "locationId": {
            "type": "string",
            "description": "BILL-generated ID of the location. The value begins with `loc`."
          }
        },
        "description": "DTO for Invoice classifications."
      },
      "InvoiceScheduleRequest": {
        "type": "object",
        "properties": {
          "period": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PeriodRequest"
              },
              {
                "description": "Time period for setting up recurring invoices"
              }
            ]
          },
          "frequency": {
            "type": "integer",
            "description": "Invoice frequency per time `period`.\n\nFor example, if the time `period` is `MONTHLY` and `frequency` is `3`, an invoice is generated once every 3 months.",
            "format": "int32"
          },
          "nextDueDate": {
            "type": "string",
            "description": "Due date for the next invoice. This value is in the `yyyy-MM-dd` format.",
            "format": "date"
          },
          "endDate": {
            "type": "string",
            "description": "End date for the recurring invoices schedule. Recurring invoices stop on the `endDate`. This value is in the `yyyy-MM-dd` format.",
            "format": "date"
          },
          "daysInAdvance": {
            "type": "integer",
            "description": "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.",
            "format": "int32"
          }
        },
        "description": "Schedule properties for a recurring Invoices."
      },
      "InvoiceScheduleResponse": {
        "type": "object",
        "properties": {
          "period": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PeriodResponse"
              },
              {
                "description": "Time period for setting up recurring invoices."
              }
            ]
          },
          "frequency": {
            "type": "integer",
            "description": "Invoice frequency per time `period`.\n\nFor example, if the time `period` is `MONTHLY` and `frequency` is `3`, an invoice is generated once every 3 months.",
            "format": "int32"
          },
          "nextDueDate": {
            "type": "string",
            "description": "Due date for the next invoice. This value is in the `yyyy-MM-dd` format.",
            "format": "date"
          },
          "endDate": {
            "type": "string",
            "description": "End date for the recurring invoices schedule. Recurring invoices stop on the `endDate`. This value is in the `yyyy-MM-dd` format.",
            "format": "date"
          },
          "daysInAdvance": {
            "type": "integer",
            "description": "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.",
            "format": "int32"
          }
        },
        "description": "Schedule properties for a recurring Invoices."
      },
      "Param": {
        "required": [
          "name",
          "value"
        ],
        "type": "object",
        "properties": {
          "additional": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "name": {
            "minLength": 1,
            "type": "string"
          },
          "value": {
            "minLength": 1,
            "type": "string"
          }
        }
      },
      "PeriodRequest": {
        "type": "string",
        "description": "Period for scheduling a recurring bill.",
        "enum": [
          "DAILY",
          "WEEKLY",
          "MONTHLY",
          "YEARLY",
          "NONE"
        ]
      },
      "PeriodResponse": {
        "type": "string",
        "description": "Period for scheduling a recurring bill.",
        "enum": [
          "DAILY",
          "WEEKLY",
          "MONTHLY",
          "YEARLY",
          "NONE",
          "UNDEFINED"
        ]
      },
      "RecurringInvoiceLineItemClassificationsDto": {
        "type": "object",
        "properties": {
          "chartOfAccountId": {
            "type": "string",
            "description": "BILL-generated ID of the chart of accounts. The value begins with `0ca`."
          },
          "accountingClassId": {
            "type": "string",
            "description": "BILL-generated ID of the accounting class. The value begins with `cls`."
          },
          "departmentId": {
            "type": "string",
            "description": "BILL-generated ID of the department. The value begins with `0de`."
          },
          "jobId": {
            "type": "string",
            "description": "BILL-generated ID of the job. The value begins with `job`."
          },
          "locationId": {
            "type": "string",
            "description": "BILL-generated ID of the location. The value begins with `loc`."
          },
          "itemId": {
            "type": "string",
            "description": "BILL-generated ID of the item. The value begins with `0ii`."
          }
        },
        "description": "DTO for Recurring Invoice Line Item classifications."
      },
      "RecurringInvoiceLineItemResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "BILL-generated ID of the recurring invoice line item. The value begins with `ril`.\n"
          },
          "amount": {
            "type": "number",
            "description": "Recurring invoice line item amount. For a recurring invoice in an international currency (not USD), this value is in the local currency."
          },
          "description": {
            "type": "string",
            "description": "Recurring invoice line item description"
          },
          "price": {
            "type": "number",
            "description": "Recurring invoice line item unit price. For a recurring invoice in an international currency (not USD), this value is in the local currency."
          },
          "quantity": {
            "type": "number",
            "description": "Recurring invoice line item unit quantity"
          },
          "classifications": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RecurringInvoiceLineItemClassificationsDto"
              },
              {
                "description": "General ledger classifications information for the recurring invoice line item"
              }
            ]
          },
          "taxable": {
            "type": "boolean",
            "description": "Set as `true` if the recurring invoice line item is taxable"
          }
        },
        "description": "Recurring Invoice Line Item."
      },
      "RecurringInvoiceReplaceLineItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "BILL-generated ID of the recurring invoice line item. The value begins with `ril`.\n"
          },
          "amount": {
            "type": "number",
            "description": "Recurring invoice line item amount. For a recurring invoice in an international currency (not USD), this value is in the local currency."
          },
          "description": {
            "maxLength": 4000,
            "type": "string",
            "description": "Recurring invoice line item description"
          },
          "price": {
            "type": "number",
            "description": "Recurring invoice line item unit price. For a recurring invoice in an international currency (not USD), this value is in the local currency."
          },
          "quantity": {
            "type": "number",
            "description": "Recurring invoice line item unit quantity"
          },
          "classifications": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RecurringInvoiceLineItemClassificationsDto"
              },
              {
                "description": "General ledger classifications information for the recurring invoice line item"
              }
            ]
          }
        },
        "description": "Replace RecurringInvoice line item request Dto."
      },
      "RecurringInvoiceReplaceRequestDto": {
        "required": [
          "customerId",
          "recurringInvoiceLineItems",
          "schedule"
        ],
        "type": "object",
        "properties": {
          "customerId": {
            "minLength": 1,
            "type": "string",
            "description": "BILL-generated ID of the customer. The value begins with `0cu`."
          },
          "paymentTermId": {
            "type": "string"
          },
          "description": {
            "maxLength": 4000,
            "type": "string",
            "description": "User-generated invoice number. This value can be your chosen number scheme or invoice due date."
          },
          "schedule": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InvoiceScheduleRequest"
              },
              {
                "description": "Recurring invoice scheduling information"
              }
            ]
          },
          "recurringInvoiceLineItems": {
            "type": "array",
            "description": "Recurring invoice line item information",
            "items": {
              "$ref": "#/components/schemas/RecurringInvoiceReplaceLineItem"
            }
          },
          "sendEmail": {
            "type": "boolean",
            "description": "Set as `true` to send an email to the customer when an invoice is created."
          }
        },
        "description": "Replace a recurring invoice (line item added)",
        "example": {
          "customerId": "{{customer_id}}",
          "schedule": {
            "period": "MONTHLY",
            "frequency": 1,
            "nextDueDate": "2026-12-31",
            "endDate": "2027-11-01",
            "daysInAdvance": 5
          },
          "recurringInvoiceLineItems": [
            {
              "id": "{{recurring_invoice_line_item_id01}}",
              "amount": 19.99,
              "description": "Monthly subscription",
              "quantity": 1
            },
            {
              "amount": 4.99,
              "description": "Decaf black tea (10 bags)",
              "quantity": 1
            }
          ]
        }
      },
      "RecurringInvoiceResponseDto": {
        "required": [
          "id"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "BILL-generated ID of the recurring invoice. The value begins with `rit`."
          },
          "customerId": {
            "type": "string",
            "description": "BILL-generated ID of the customer. The value begins with `0cu`."
          },
          "paymentTermId": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "description": "Recurring invoice line item description"
          },
          "archived": {
            "type": "boolean",
            "description": "Set as `true` if the recurring invoice is archived"
          },
          "schedule": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InvoiceScheduleResponse"
              },
              {
                "description": "Recurring invoice scheduling information"
              }
            ]
          },
          "recurringInvoiceLineItems": {
            "type": "array",
            "description": "Recurring invoice line item information",
            "items": {
              "$ref": "#/components/schemas/RecurringInvoiceLineItemResponseDto"
            }
          },
          "classifications": {
            "allOf": [
              {
                "$ref": "#/components/schemas/InvoiceClassificationsDto"
              },
              {
                "description": "General ledger classifications information for the recurring invoice line item"
              }
            ]
          },
          "sendEmail": {
            "type": "boolean",
            "description": "Set as `true` to send an email to the customer when an invoice is created."
          },
          "createdTime": {
            "type": "string",
            "description": "Created date and time",
            "format": "date-time"
          },
          "updatedTime": {
            "type": "string",
            "description": "Updated date and time",
            "format": "date-time"
          }
        },
        "description": "RecurringInvoice response Dto."
      },
      "Severity": {
        "type": "string",
        "enum": [
          "ERROR",
          "WARNING",
          "INFORMATION"
        ]
      }
    }
  }
}
```