Recurring Invoices API¶
A recurring invoice is a schedule that automatically generates managed invoices at a fixed cadence. You define the frequency, an invoice template, and the business profile and customer to bill, and InvoicePDFs creates a new invoice on each occurrence. Schedules can be paused, resumed, and cancelled, and you can list every invoice a schedule has produced.
Create Recurring Invoice¶
The schedule is created in active status and its first occurrence is set to start_date. The referenced business profile, customer, and (if supplied) numbering sequence must already exist.
Request:
{
"business_profile_id": "bp_01ABC",
"customer_id": "cus_01XYZ",
"frequency": "monthly",
"interval": 1,
"start_date": "2026-08-01",
"end_date": "2027-08-01",
"max_occurrences": 12,
"numbering_sequence_id": "seq_01ABC",
"auto_finalize": true,
"invoice_template": {
"invoice_number": "INV-RECURRING",
"issue_date": "2026-08-01",
"currency": "USD",
"business_profile_id": "bp_01ABC",
"customer_id": "cus_01XYZ",
"line_items": [
{
"name": "Monthly retainer",
"quantity": "1",
"unit_price": "500.00"
}
]
}
}
| Field | Required | Description |
|---|---|---|
business_profile_id |
Yes | Business profile (seller) to bill from |
customer_id |
Yes | Customer (buyer) to bill |
frequency |
Yes | One of daily, weekly, monthly, quarterly, yearly |
interval |
No | Run every N periods (default 1) |
start_date |
Yes | Date of the first generated invoice |
end_date |
No | Stop generating after this date |
max_occurrences |
No | Stop after this many invoices |
numbering_sequence_id |
No | Auto-generate invoice numbers from this sequence |
auto_finalize |
No | Automatically finalize each generated invoice (default false) |
invoice_template |
Yes | Invoice payload used as the template for each occurrence (same shape as the Create Document request) |
Response 200 OK:
{
"data": {
"id": "rinv_01ABC",
"status": "active",
"business_profile_id": "bp_01ABC",
"customer_id": "cus_01XYZ",
"frequency": "monthly",
"interval": 1,
"next_occurrence_date": "2026-08-01",
"end_date": "2027-08-01",
"occurrences_created": 0,
"max_occurrences": 12,
"numbering_sequence_id": "seq_01ABC",
"auto_finalize": true,
"created_at": "2026-07-20T10:00:00Z",
"updated_at": "2026-07-20T10:00:00Z"
}
}
Try it
List Recurring Invoices¶
Supports an optional status query parameter (for example active, paused, or cancelled) to filter the results.
Response:
{
"data": [
{
"id": "rinv_01ABC",
"status": "active",
"business_profile_id": "bp_01ABC",
"customer_id": "cus_01XYZ",
"frequency": "monthly",
"interval": 1,
"next_occurrence_date": "2026-08-01",
"end_date": "2027-08-01",
"occurrences_created": 0,
"max_occurrences": 12,
"numbering_sequence_id": "seq_01ABC",
"auto_finalize": true,
"created_at": "2026-07-20T10:00:00Z",
"updated_at": "2026-07-20T10:00:00Z"
}
],
"pagination": {
"has_more": false,
"next_cursor": null
}
}
Try it
Get Recurring Invoice¶
Response:
{
"data": {
"id": "rinv_01ABC",
"status": "active",
"business_profile_id": "bp_01ABC",
"customer_id": "cus_01XYZ",
"frequency": "monthly",
"interval": 1,
"next_occurrence_date": "2026-08-01",
"end_date": "2027-08-01",
"occurrences_created": 0,
"max_occurrences": 12,
"numbering_sequence_id": "seq_01ABC",
"auto_finalize": true,
"created_at": "2026-07-20T10:00:00Z",
"updated_at": "2026-07-20T10:00:00Z"
}
}
Try it
Update Recurring Invoice¶
Only include the fields you want to change:
| Field | Required | Description |
|---|---|---|
frequency |
No | One of daily, weekly, monthly, quarterly, yearly |
interval |
No | Run every N periods |
end_date |
No | Stop generating after this date |
max_occurrences |
No | Stop after this many invoices |
numbering_sequence_id |
No | Numbering sequence used for generated invoice numbers |
auto_finalize |
No | Whether generated invoices are finalized automatically |
invoice_template |
No | Replacement invoice template for future occurrences |
Note
A recurring invoice in cancelled status cannot be updated and returns 409 Conflict.
Response 200 OK: the updated recurring invoice object (same shape as Get Recurring Invoice).
Try it
Pause Recurring Invoice¶
Pauses an active schedule so no new invoices are generated until it is resumed. Only active schedules can be paused; otherwise 409 Conflict is returned.
Response 200 OK:
{
"data": {
"id": "rinv_01ABC",
"status": "paused",
"business_profile_id": "bp_01ABC",
"customer_id": "cus_01XYZ",
"frequency": "monthly",
"interval": 1,
"next_occurrence_date": "2026-08-01",
"end_date": "2027-08-01",
"occurrences_created": 0,
"max_occurrences": 12,
"numbering_sequence_id": "seq_01ABC",
"auto_finalize": true,
"created_at": "2026-07-20T10:00:00Z",
"updated_at": "2026-07-20T12:00:00Z"
}
}
Try it
Resume Recurring Invoice¶
Returns a paused schedule to active status. Only paused schedules can be resumed; otherwise 409 Conflict is returned.
Response 200 OK: the recurring invoice object with status set to active.
Try it
Cancel Recurring Invoice¶
Cancels the schedule permanently. Its status becomes cancelled and next_occurrence_date is cleared, so no further invoices are generated. Cancelling an already-cancelled schedule returns 409 Conflict.
Response 200 OK:
{
"data": {
"id": "rinv_01ABC",
"status": "cancelled",
"business_profile_id": "bp_01ABC",
"customer_id": "cus_01XYZ",
"frequency": "monthly",
"interval": 1,
"next_occurrence_date": null,
"end_date": "2027-08-01",
"occurrences_created": 3,
"max_occurrences": 12,
"numbering_sequence_id": "seq_01ABC",
"auto_finalize": true,
"created_at": "2026-07-20T10:00:00Z",
"updated_at": "2026-07-20T13:00:00Z"
}
}
Try it
List Generated Invoices¶
Returns the managed invoices this schedule has produced, newest first. Each item is a full invoice object (same shape as the Documents API).
Response:
{
"data": [
{
"id": "inv_01ABC",
"status": "finalized",
"invoice_number": "INV-2026-00001",
"document_type": "invoice",
"issue_date": "2026-08-01",
"currency": "USD",
"business_profile_id": "bp_01ABC",
"customer_id": "cus_01XYZ"
}
],
"pagination": {
"has_more": false,
"next_cursor": null
}
}