--- updatedAt: 2026-03-05T19:16:22.000Z agentTools: projectIndex: https://developer.bill.com/v2/llms.txt --- # Create a recurring invoice Create a recurring invoice object. ### What is a recurring invoice? A recurring invoice is an identical invoice created to receive periodic payments from a customer. These invoices represent an amount that you are owed by a customer for goods and services that you provide. You can create a recurring invoice with [`/v2/Crud/Create/RecurringInvoice.json`](ref:ar-customertransactions-createrecurringinvoice). In the invoice, add invoice line items to record details about individual goods or services. In addition, you can associate line items to accounts tracking objects, such as item ([`/Item.json`](ref:org-accounts-createitem)) or chart of accounts ([`/ChartOfAccounts.json`](ref:org-accounts-createchartofaccount)). Other invoice features: * Recurring invoice numbers are automatically set as the invoice due date in the YYYY-MM-DD format. * You can reduce the total invoice amount with an invoice credit ([`/CreditMemo.json`](ref:ar-customertransactions-createcreditmemo)). Total invoice amount, credit memos, and any remaining invoice amount to be paid or recorded is available with [`/v2/Crud/Read/ReceivedPay.json`](ref:ar-customertransactions-receivedpay). * You can send invoices to the customer by email ([`/v2/SendInvoice.json`](ref:ar-customertransactions-sendinvoice)) or US mail ([`/v2/MailInvoice.json`](ref:ar-customertransactions-mailinvoice)). ### Line item price, markups, & discounts In your request, either `price` or percentage (`ratePercent`) is required for each `recurringInvoiceLineItems` object. If you set one, do not set the other. * If `price` is set, `amount` is (`quantity`) x (`price`). * If `ratePercent` is set for a line item, the line item `amount` is (`ratePercent`) x (sum of other line item `amount` values). For example, to apply a discount of 20% in your invoice total of $100, set `ratePercent` as `-20` in the final line item of your request. ``` "recurringInvoiceLineItems": [ { "entity": "recurringInvoiceLineItem", "description": "item 01", "quantity": 1, "price": 50, "amount": 50 }, { "entity": "recurringInvoiceLineItem", "description": "item 02", "quantity": 2, "price": 25, "amount": 50 }, { "entity": "recurringInvoiceLineItem", "description": "discount", "quantity": 1, "ratePercent": -20 } ] ``` # OpenAPI definition ````json { "openapi": "3.0.0", "info": { "title": "AR | Customer transactions", "version": "2.0", "description": "BILL is a cloud-based cash flow management system for an organization's Accounts Payable (AP) and Accounts Receivable (AR) automation.\n * **AP**: Automate workflows to pay vendors bills at scale for the goods and services they provide. Pay vendors with a wide range of payment methods. Generate vendor credits, bill credits, and payment disbursement reports.\n * **AR**: Automate workflows to get paid by customers at scale for the goods and services you provide. Generate and send invoices on a schedule, generate customer and invoice credits, and seamlessly charge authorized customers.\n * **Organization**: Manage your bank accounts (for sending and receiving payments), users (with user roles), and sync with your choice of accounting software.\n\nIntegrate with the BILL API to send and receive payments for your business. See [Support Center](https://help.bill.com/hc/en-us) for resources about using the BILL web app.", "contact": { "email": "developerprogram@hq.bill.com" } }, "servers": [ { "url": "https://api-stage.bill.com/api/v2", "description": "Sandbox base URL" } ], "x-readme": { "samples-languages": [ "curl", "java", "javascript", "python", "ruby" ] }, "paths": { "/Crud/Create/RecurringInvoice.json": { "post": { "summary": "Create a recurring invoice", "operationId": "ar-customertransactions-createrecurringinvoice", "description": "Create a recurring invoice object.\n### What is a recurring invoice?\nA recurring invoice is an identical invoice created to receive periodic payments from a customer. These invoices represent an amount that you are owed by a customer for goods and services that you provide.\n\nYou can create a recurring invoice with [`/v2/Crud/Create/RecurringInvoice.json`](https://developer.bill.com/reference/ar-customertransactions-createrecurringinvoice). In the invoice, add invoice line items to record details about individual goods or services. In addition, you can associate line items to accounts tracking objects, such as item ([`/Item.json`](https://developer.bill.com/reference/org-accounts-createitem)) or chart of accounts ([`/ChartOfAccounts.json`](https://developer.bill.com/reference/org-accounts-createchartofaccount)).\n\nOther invoice features:\n* Recurring invoice numbers are automatically set as the invoice due date in the YYYY-MM-DD format.\n* You can reduce the total invoice amount with an invoice credit ([`/CreditMemo.json`](https://developer.bill.com/reference/ar-customertransactions-createcreditmemo)). Total invoice amount, credit memos, and any remaining invoice amount to be paid or recorded is available with [`/v2/Crud/Read/ReceivedPay.json`](https://developer.bill.com/reference/ar-customertransactions-receivedpay).\n* You can send invoices to the customer by email ([`/v2/SendInvoice.json`](https://developer.bill.com/reference/ar-customertransactions-sendinvoice)) or US mail ([`/v2/MailInvoice.json`](https://developer.bill.com/reference/ar-customertransactions-mailinvoice)).\n\n### Line item price, markups, & discounts\nIn your request, either `price` or percentage (`ratePercent`) is required for each `recurringInvoiceLineItems` object. If you set one, do not set the other.\n* If `price` is set, `amount` is (`quantity`) x (`price`).\n* If `ratePercent` is set for a line item, the line item `amount` is (`ratePercent`) x (sum of other line item `amount` values). For example, to apply a discount of 20% in your invoice total of $100, set `ratePercent` as `-20` in the final line item of your request.\n```\n \"recurringInvoiceLineItems\": [\n {\n \"entity\": \"recurringInvoiceLineItem\",\n \"description\": \"item 01\",\n \"quantity\": 1,\n \"price\": 50,\n \"amount\": 50\n },\n {\n \"entity\": \"recurringInvoiceLineItem\",\n \"description\": \"item 02\",\n \"quantity\": 2,\n \"price\": 25,\n \"amount\": 50\n },\n {\n \"entity\": \"recurringInvoiceLineItem\",\n \"description\": \"discount\",\n \"quantity\": 1,\n \"ratePercent\": -20\n }\n ]\n``` ", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecurringInvoiceResponse" } } } } }, "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "devKey", "sessionId", "data" ], "properties": { "devKey": { "type": "string", "description": "Developer key generated with your BILL developer account" }, "sessionId": { "type": "string", "description": "API session ID generated with [`/v2/Login.json`](https://developer.bill.com/reference/auth-login)" }, "data": { "$ref": "#/components/schemas/CreateRecurringInvoiceRequest" } } } } } }, "tags": [ "Recurring invoices" ] }, "parameters": [] } }, "components": { "schemas": { "ErrorResponse": { "type": "object", "properties": { "error_code": { "type": "string", "description": "Error code (only when `response_status` is `1`)" }, "error_message": { "type": "string", "description": "Error message (only when `response_status` is `1`)" } } }, "CreateRecurringInvoiceRequest": { "type": "object", "required": [ "obj" ], "properties": { "obj": { "type": "object", "required": [ "entity", "customerId", "timePeriod", "frequencyPerTimePeriod", "nextDueDate", "daysInAdvance", "recurringInvoiceLineItems" ], "properties": { "entity": { "type": "string", "description": "Object type. Set as `RecurringInvoice`.", "default": "RecurringInvoice" }, "isActive": { "type": "string", "description": "Object visibility status. Inactive objects are hidden by default in the BILL web app.\n* `1`: Active\n* `2`: Inactive" }, "customerId": { "type": "string", "description": "BILL-generated ID of the customer. The value begins with `0cu`." }, "poNumber": { "type": "string", "description": "Purchase order number associated with the invoice" }, "salesRep": { "type": "string", "description": "Sales representative associated with the invoice" }, "departmentId": { "type": "string", "description": "BILL-generated ID of the department associated with the invoice. This is an accounts tracking object." }, "locationId": { "type": "string", "description": "BILL-generated ID of the location associated with the invoice. This is an accounts tracking object." }, "actgClassId": { "type": "string", "description": "BILL-generated ID of the accounting class associated with the invoice. This is an accounts tracking object." }, "jobId": { "type": "string", "description": "BILL-generated ID of the job associated with the invoice. This is an accounts tracking object." }, "itemSalesTax": { "type": "string", "description": "BILL-generated ID of the sales tax applied to all taxable line items in the invoice. The value begins with `0ii`. The `salesTaxTotal` in the response is calculated based on the `itemSalesTax` value.\n\nYou can set your sales tax value with the BILL web app. On the **Settings** page, click **Classifications** under **Accounting**, and then create a new item with the **TYPE** set as **Sales Tax**." }, "description": { "type": "string", "description": "Invoice description" }, "isToBePrinted": { "type": "boolean", "description": "Set as `true` if the invoice is to be printed and mailed to the customer" }, "isToBeEmailed": { "type": "boolean", "description": "Set as `true` if the invoice is to be emailed to the customer" }, "isToBeAutoEmailed": { "type": "boolean", "description": "Set as `true` if the generated invoice is automatically emailed to the customer. BILL uses the default email template and sends the email to all the customer and customer contacts recipients." }, "fromUserId": { "type": "string", "description": "BILL-generated ID of the user that set up recurring invoices. The value begins with `006`." }, "paymentTermId": { "type": "string", "description": "BILL-generated payment term ID for the customer. The payment term defines when a payment is sent." }, "invoiceTemplateId": { "type": "string", "description": "BILL-generated ID of the invoice template" }, "timePeriod": { "type": "string", "description": "Time period.\n* `0`: Day\n* `1`: Week\n* `2`: Month\n* `3`: Year\n* `9`: None" }, "frequencyPerTimePeriod": { "type": "integer", "description": "Invoice frequency per `timePeriod`.\n\nFor example, if `timePeriod` is `2` and `frequencyPerTimePeriod` is `3`, an invoice is generated once every 3 months." }, "nextDueDate": { "type": "string", "description": "Due date of the next invoice in the YYYY-MM-DD format" }, "endDate": { "type": "string", "description": "Date after which the recurring invoices stop. This value is in the YYYY-MM-DD format." }, "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." }, "recurringInvoiceLineItems": { "type": "array", "items": { "type": "object", "required": [ "entity", "amount", "quantity" ], "properties": { "entity": { "type": "string", "description": "Object type. Set as `RecurringInvoiceLineItem`.", "default": "RecurringInvoiceLineItem" }, "chartOfAccountId": { "type": "string", "description": "BILL-generated ID of the chart of accounts associated with the recurring invoice line item. This is an accounts tracking object." }, "departmentId": { "type": "string", "description": "BILL-generated ID of the department associated with the recurring invoice line item. This is an accounts tracking object." }, "locationId": { "type": "string", "description": "BILL-generated ID of the location associated with the recurring invoice line item. This is an accounts tracking object." }, "actgClassId": { "type": "string", "description": "BILL-generated ID of the accounting class associated with the recurring invoice line item. This is an accounts tracking object." }, "jobId": { "type": "string", "description": "BILL-generated ID of the job associated with the recurring invoice line item. This is an accounts tracking object." }, "description": { "type": "string", "description": "Recurring invoice line item description" }, "itemId": { "type": "string", "description": "BILL-generated ID of the item associated with the recurring invoice line item. This is an accounts tracking object." }, "amount": { "type": "number", "description": "Invoice line item total amount. If `ratePercent` is set, `amount` is (`ratePercent`) x (sum of other line item `amount` values). If `price` is set, `amount` is (`quantity`) x (`price`)." }, "quantity": { "type": "number", "description": "Quantity of items sold or time spent providing the service" }, "price": { "type": "number", "description": "Item price or service rate" }, "ratePercent": { "type": "number", "description": "Item rate percentage.\n* A positive value is a markup. For example, set as `20` for a `20%` markup.\n* A negative value is a discount. For example, set as `-20` for a `20%` discount." }, "taxable": { "type": "boolean", "description": "Set as `true` if the invoice line item is taxable and is included in the `salesTaxTotal` calculation" } } } } } } } }, "CreateRecurringInvoiceResponse": { "type": "object", "properties": { "response_status": { "type": "integer", "description": "Response status.\n* `0`: Success response\n* `1`: Error response. Only `error_code` and `error_message` is returned in `response_data`." }, "response_message": { "type": "string", "description": "Response status.\n* `Success`: Success response\n* `Error`: Error response. Only `error_code` and `error_message` is returned in `response_data`." }, "response_data": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" } ], "properties": { "entity": { "type": "string", "description": "Object type. Set as `RecurringInvoice`." }, "id": { "type": "string", "description": "BILL-generated ID of the recurring invoice. The value begins with `rit`." }, "isActive": { "type": "string", "description": "Object visibility status. Inactive objects are hidden by default in the BILL web app.\n* `1`: Active\n* `2`: Inactive" }, "customerId": { "type": "string", "description": "BILL-generated ID of the customer. The value begins with `0cu`." }, "poNumber": { "type": "string", "description": "Purchase order number associated with the invoice" }, "salesRep": { "type": "string", "description": "Sales representative associated with the invoice" }, "departmentId": { "type": "string", "description": "BILL-generated ID of the department associated with the invoice. This is an accounts tracking object." }, "locationId": { "type": "string", "description": "BILL-generated ID of the location associated with the invoice. This is an accounts tracking object." }, "actgClassId": { "type": "string", "description": "BILL-generated ID of the accounting class associated with the invoice. This is an accounts tracking object." }, "jobId": { "type": "string", "description": "BILL-generated ID of the job associated with the invoice. This is an accounts tracking object." }, "itemSalesTax": { "type": "string", "description": "BILL-generated ID of the sales tax applied to all taxable line items in the invoice. The value begins with `0ii`. The `salesTaxTotal` in the response is calculated based on the `itemSalesTax` value.\n\nYou can set your sales tax value with the BILL web app. On the **Settings** page, click **Classifications** under **Accounting**, and then create a new item with the **TYPE** set as **Sales Tax**." }, "description": { "type": "string", "description": "Invoice description" }, "isToBePrinted": { "type": "boolean", "description": "Set as `true` if the invoice is to be printed and mailed to the customer" }, "isToBeEmailed": { "type": "boolean", "description": "Set as `true` if the invoice is to be emailed to the customer" }, "isToBeAutoEmailed": { "type": "boolean", "description": "Set as `true` if the generated invoice is automatically emailed to the customer. BILL uses the default email template and sends the email to all the customer and customer contacts recipients." }, "fromUserId": { "type": "string", "description": "BILL-generated ID of the user that set up recurring invoices. The value begins with `006`." }, "paymentTermId": { "type": "string", "description": "BILL-generated payment term ID for the customer. The payment term defines when a payment is sent." }, "invoiceTemplateId": { "type": "string", "description": "BILL-generated ID of the invoice template" }, "timePeriod": { "type": "string", "description": "Time period.\n* `0`: Day\n* `1`: Week\n* `2`: Month\n* `3`: Year\n* `9`: None" }, "frequencyPerTimePeriod": { "type": "integer", "description": "Invoice frequency per `timePeriod`.\n\nFor example, if `timePeriod` is `2` and `frequencyPerTimePeriod` is `3`, an invoice is generated once every 3 months." }, "nextDueDate": { "type": "string", "description": "Due date of the next invoice in the YYYY-MM-DD format" }, "endDate": { "type": "string", "description": "Date after which the recurring invoices stop. This value is in the YYYY-MM-DD format." }, "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." }, "taxableAmount": { "type": "number", "description": "Total taxable invoice amount" }, "subtotal": { "type": "number", "description": "Total invoice amount without taxes" }, "createdTime": { "type": "string", "description": "Created date and time" }, "updatedTime": { "type": "string", "description": "Updated date and time" }, "recurringInvoiceLineItems": { "type": "array", "items": { "type": "object", "properties": { "entity": { "type": "string", "description": "Object type. Set as `RecurringInvoiceLineItem`." }, "id": { "type": "string", "description": "BILL-generated recurring invoice line item ID. The value begins with `ril`." }, "chartOfAccountId": { "type": "string", "description": "BILL-generated ID of the chart of accounts associated with the recurring invoice line item. This is an accounts tracking object." }, "departmentId": { "type": "string", "description": "BILL-generated ID of the department associated with the recurring invoice line item. This is an accounts tracking object." }, "locationId": { "type": "string", "description": "BILL-generated ID of the location associated with the recurring invoice line item. This is an accounts tracking object." }, "actgClassId": { "type": "string", "description": "BILL-generated ID of the accounting class associated with the recurring invoice line item. This is an accounts tracking object." }, "jobId": { "type": "string", "description": "BILL-generated ID of the job associated with the recurring invoice line item. This is an accounts tracking object." }, "description": { "type": "string", "description": "Recurring invoice line item description" }, "recurringInvoiceId": { "type": "string", "description": "BILL-generated ID of the recurring invoice. The value begins with `rit`." }, "itemId": { "type": "string", "description": "BILL-generated ID of the item associated with the recurring invoice. This is an accounts tracking object." }, "amount": { "type": "number", "description": "Invoice line item total amount. If `ratePercent` is set, `amount` is (`ratePercent`) x (sum of other line item `amount` values). If `price` is set, `amount` is (`quantity`) x (`price`)." }, "quantity": { "type": "number", "description": "Quantity of items sold or time spent providing the service" }, "price": { "type": "number", "description": "Item price or service rate" }, "ratePercent": { "type": "number", "description": "Item rate percentage.\n* A positive value is a markup. For example, set as `20` for a `20%` markup.\n* A negative value is a discount. For example, set as `-20` for a `20%` discount." }, "taxable": { "type": "boolean", "description": "Set as `true` if the invoice line item is taxable and is included in the `salesTaxTotal` calculation" }, "createdTime": { "type": "string", "description": "Created date and time" }, "updatedTime": { "type": "string", "description": "Updated date and time" } } } } } } } } } } } ````