--- updatedAt: 2026-06-29T20:33:19.000Z agentTools: projectIndex: https://developer.bill.com/llms.txt --- # Create a recurring bill Create a recurring bill. See [Recurring bills](https://developer.bill.com/docs/ap-recurring-bills) in the Guides section for more information, sample requests, and responses. # 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/recurringbills": { "post": { "tags": [ "recurringbills" ], "summary": "Create a recurring bill", "description": "Create a recurring bill.\n\nSee [Recurring bills](https://developer.bill.com/docs/ap-recurring-bills) in the Guides section for more information, sample requests, and responses.", "operationId": "createRecurringBill", "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}}" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringBillCreateRequestDto" } } }, "required": true }, "responses": { "201": { "description": "Create a recurring bill response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringBillResponseDto" } } } }, "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" ] }, "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" ] }, "RecurringBillCreateLineItem": { "required": [ "amount" ], "type": "object", "properties": { "amount": { "type": "number", "description": "Recurring bill line item amount. For a bill in an international currency (not USD), this value is in the local currency." }, "description": { "maxLength": 4000, "type": "string", "description": "Recurring bill line item description" }, "price": { "type": "number", "description": "Recurring bill line item price" }, "quantity": { "type": "number", "description": "Recurring bill line item quantity" }, "classifications": { "allOf": [ { "$ref": "#/components/schemas/RecurringBillLineItemClassificationsDto" }, { "description": "General ledger classifications information for the recurring bill line item" } ] } }, "description": "Line items that define a bill's overall amount." }, "RecurringBillCreateRequestDto": { "required": [ "recurringBillLineItems", "schedule", "vendorId" ], "type": "object", "properties": { "vendorId": { "minLength": 1, "type": "string", "description": "BILL-generated ID of the vendor. The value begins with `009`." }, "description": { "maxLength": 4000, "type": "string", "description": "User-generated invoice number. This value can be your chosen number scheme or bill due date." }, "schedule": { "allOf": [ { "$ref": "#/components/schemas/ScheduleRequest" }, { "description": "Recurring bill scheduling information" } ] }, "recurringBillLineItems": { "type": "array", "description": "Recurring bill line item information", "items": { "$ref": "#/components/schemas/RecurringBillCreateLineItem" } }, "processingOptions": { "allOf": [ { "$ref": "#/components/schemas/RecurringBillProcessingOptions" }, { "description": "Payment processing options.\n\n**Note**: Enabling recurring bill `autoPayment` requires an MFA-trusted API session. See [MFA setup](https://developer.bill.com/reference/setup) for information about the BILL MFA process." } ] }, "paymentInformation": { "allOf": [ { "$ref": "#/components/schemas/RecurringBillPaymentInformation" }, { "description": "Payment information" } ] } }, "description": "Create a recurring bill", "example": { "vendorId": "{{vendor_id}}", "schedule": { "period": "MONTHLY", "frequency": 1, "nextDueDate": "2026-12-31", "endDate": "2027-11-01", "daysInAdvance": 5 }, "recurringBillLineItems": [ { "amount": 19.99, "description": "Monthly subscription" } ], "processingOptions": { "autoPayment": true }, "paymentInformation": { "bankAccountId": "{{org_bank_account_id}}" } } }, "RecurringBillLineItemClassificationsDto": { "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`." }, "employeeId": { "type": "string", "description": "BILL-generated ID of the employee. The value begins with `emp`." }, "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`." }, "customerId": { "type": "string", "description": "BILL-generated ID of the customer. The value begins with `0cu`." } }, "description": "DTO for Bill Line Item classifications." }, "RecurringBillPaymentInformation": { "type": "object", "properties": { "bankAccountId": { "type": "string", "description": "BILL-generated ID of the bank account used to pay each bill. The value begins with `bac`." }, "cardAccountId": { "type": "string", "description": "BILL-generated ID of the card account used to pay each bill. The value begins with `cat`." } }, "description": "Payment info for a recurring bill." }, "RecurringBillProcessingOptions": { "type": "object", "properties": { "autoPayment": { "type": "boolean", "description": "Set as `true` to enable auto-payment for each bill" } }, "description": "User provided options for processing the recurring payment." }, "RecurringBillResponseDto": { "required": [ "archived", "billsCount", "expired", "id", "recurringBillLineItems", "schedule", "vendorId" ], "type": "object", "properties": { "id": { "type": "string", "description": "BILL-generated ID of the recurring bill. The value begins with `btp`." }, "archived": { "type": "boolean", "description": "Set as `true` if the recurring bill is archived" }, "vendorId": { "type": "string", "description": "BILL-generated ID of the vendor. The value begins with `009`." }, "description": { "type": "string", "description": "Recurring bill description" }, "billsCount": { "type": "integer", "description": "Number of bills generated from this recurring bill", "format": "int32" }, "amount": { "type": "number", "description": "Recurring bill total amount" }, "expired": { "type": "boolean", "description": "Set as `true` if the recurring bill is expired" }, "schedule": { "allOf": [ { "$ref": "#/components/schemas/ScheduleResponse" }, { "description": "Recurring bill scheduling information" } ] }, "recurringBillLineItems": { "type": "array", "description": "Recurring bill line item information", "items": { "$ref": "#/components/schemas/RecurringBillResponseLineItem" } }, "processingOptions": { "allOf": [ { "$ref": "#/components/schemas/RecurringBillProcessingOptions" }, { "description": "Payment processing options" } ] }, "paymentInformation": { "allOf": [ { "$ref": "#/components/schemas/RecurringBillPaymentInformation" }, { "description": "Payment information" } ] }, "createdTime": { "type": "string", "description": "Created date and time", "format": "date-time" }, "updatedTime": { "type": "string", "description": "Updated date and time", "format": "date-time" } }, "description": "Recurring bills response." }, "RecurringBillResponseLineItem": { "required": [ "amount" ], "type": "object", "properties": { "id": { "type": "string", "description": "BILL-generated ID of the recurring bill line item. The value begins with `tli`." }, "amount": { "type": "number", "description": "Recurring bill line item amount. For a bill in an international currency (not USD), this value is in the local currency." }, "description": { "type": "string", "description": "Recurring bill line item description" }, "price": { "type": "number", "description": "Recurring bill line item price" }, "quantity": { "type": "number", "description": "Recurring bill line item quantity" }, "classifications": { "allOf": [ { "$ref": "#/components/schemas/RecurringBillLineItemClassificationsDto" }, { "description": "General ledger classifications information for the recurring bill line item" } ] } }, "description": "Line items that define a bill's overall amount." }, "ScheduleRequest": { "type": "object", "properties": { "period": { "allOf": [ { "$ref": "#/components/schemas/PeriodRequest" }, { "description": "Time period for setting up recurring bills" } ] }, "frequency": { "type": "integer", "description": "Bill frequency per time `period`.\n\nFor example, if the time `period` is `MONTHLY` and `frequency` is `3`, a bill is generated once every 3 months.", "format": "int32" }, "nextDueDate": { "type": "string", "description": "Due date for the next bill. This value is in the `yyyy-MM-dd` format.", "format": "date" }, "endDate": { "type": "string", "description": "End date for the recurring bills schedule. Recurring bills 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 bill is generated. If the date has occurred in the past for one or more bills, all those bills are generated.", "format": "int32" } }, "description": "Schedule properties for a recurring bill." }, "ScheduleResponse": { "type": "object", "properties": { "period": { "allOf": [ { "$ref": "#/components/schemas/PeriodResponse" }, { "description": "Time period for setting up recurring bills" } ] }, "frequency": { "type": "integer", "description": "Bill frequency per time `period`.\n\nFor example, if the time `period` is `MONTHLY` and `frequency` is `3`, a bill is generated once every 3 months.", "format": "int32" }, "nextDueDate": { "type": "string", "description": "Due date for the next bill. This value is in the `yyyy-MM-dd` format.", "format": "date" }, "endDate": { "type": "string", "description": "End date for the recurring bills schedule. Recurring bills 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 bill is generated. If the date has occurred in the past for one or more bills, all those bills are generated.", "format": "int32" } }, "description": "Schedule properties for a recurring bill." }, "Severity": { "type": "string", "enum": [ "ERROR", "WARNING", "INFORMATION" ] } } } } ```