Recurring Invoices

This section covers the Recurring Invoices API for creating and managing automated invoice schedules. Schedules generate invoices on a recurring basis (weekly, monthly, quarterly, yearly, or on custom dates) and can optionally auto-deliver them by email.

Requires the RECURRING_INVOICE subscription feature and apiKeyAuth.

---

Endpoints

Endpoint	Method	Description
GET /recurring-invoices	GET	Paginated list of all schedules. Supports filtering and sorting.
GET /recurring-invoice/{id}	GET	Get a single schedule by ID.
POST /recurring-invoice	POST	Create a new schedule. Immediately set to active.
PATCH /recurring-invoice/{id}	PATCH	Update schedule fields (partial update).
PATCH /recurring-invoice/{id}/{status}	PATCH	Change schedule status (active, paused, or cancelled).

---

Frequency Types

Every schedule has a frequency that determines when invoices are generated.

Frequency	nthDay	monthOffset	startDate	endDate	customDates
weekly	0 – 6 (day of week, 0 = Sunday)	—	required	optional	—
monthly	1 – 31 (day of month)	—	required	optional	—
quarterly	1 – 31 (day of month)	0 – 2 (month within quarter)	required	optional	—
yearly	1 – 31 (day of month)	1 – 12 (month)	required	optional	—
custom	—	—	optional	optional	required

All dates use ISO 8601 format (2025-01-15T00:00:00.000Z).

---

Query Parameters for GET /recurring-invoices

Parameter	Type	Description
offset	number	Number of records to skip (default: 0).
limit	number	Number of records to return.
sort	string	Sort by: createdAt, startDate, endDate, or name.
order	string	Sort direction: asc or desc.
status[]	string[]	Filter by status: active, paused, cancelled, draft.
keyword	string	Full-text search across schedule fields.

---

Schedule Fields (Create / Update)

Scheduling

Field	Type	Required	Description
frequency	string	create	One of: weekly, monthly, quarterly, yearly, custom.
nthDay	integer	create*	Day of occurrence. Range depends on frequency (see table above).
monthOffset	integer	create*	Month offset within period. Required for quarterly and yearly.
startDate	string	create*	ISO 8601 date-time. Required for all frequencies except custom.
endDate	string		ISO 8601 date-time. Schedule stops after this date.
customDates	array	create*	Array of ISO 8601 date-time strings. Required for custom only.

Template

Field	Type	Description
name	string	Display name for the schedule (max 255 characters).
subject	string	Invoice subject line.
currency	string	ISO 4217 currency code (e.g., EUR, USD).
invoiceItems	array	Array of invoice line items (same schema as POST /invoices).
issueDateOffset	integer	Days to offset the issue date from the execution date.
lastPaymentDateOffset	integer	Days to offset the payment due date.
deliveryDateOffset	integer	Days to offset the delivery date.
invoiceTypeCode	number	Invoice type code (e.g., 380 for standard invoice).
autoDelivery	boolean	When true, generated invoices are automatically sent by email.

Customer

The customer object sets the invoice recipient. You can link an existing customer by faktooraCustomerId or provide inline address data.

Field	Type	Description
faktooraCustomerId	string	UUID of an existing customer (auto-populates snapshot).
name	string	Company name.
firstName	string	First name (individuals).
lastName	string	Last name (individuals).
address	string	Street address.
postcode	string	Postal code.
city	string	City.
country	string	ISO 3166-1 alpha-2 country code.
email	string	Contact email.
vatId	string	VAT registration number.
taxId	string	Tax ID.

Delivery Email

The deliveryEmail object configures automatic email delivery when autoDelivery is enabled.

Field	Type	Required	Description
to	string	yes	Recipient email.
cc	string		CC email.
bcc	string		BCC email.
subject	string		Email subject line.
message	string		Email body text.

---

Response Object

GET endpoints return schedule objects with the following shape:

Field	Type	Description
id	string	Schedule UUID.
name	string	Display name.
frequency	string	weekly, monthly, quarterly, yearly, or custom.
nthDay	integer	Day of occurrence.
monthOffset	integer	Month offset within period.
startDate	string	ISO 8601 start date.
endDate	string	ISO 8601 end date (or null).
status	string	active, paused, cancelled, or draft.
autoDelivery	boolean	Whether invoices are auto-sent.
nextExecutionDate	string	Computed ISO 8601 date of next pending invoice (or null).
createdAt	string	ISO 8601 creation timestamp.
updatedAt	string	ISO 8601 last update timestamp.
template	object	Nested template summary (see below).

Template Object

Field	Type	Description
id	string	Template UUID.
subject	string	Invoice subject line.
currency	string	ISO 4217 currency code.
amount	number	Total invoice amount.
customer	object	{ name, firstName, lastName, email, country } or null.

---

Status Transitions

From	Allowed transitions
active	paused, cancelled
paused	active, cancelled
cancelled	(terminal — no transitions)

Cancelling a schedule also cancels all pending tasks. This action cannot be undone.

---

Examples

Example: Create a monthly recurring invoice

curl -X POST \
  -H "X-API-KEY: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "frequency": "monthly",
    "nthDay": 1,
    "startDate": "2025-02-01T00:00:00.000Z",
    "name": "Monthly hosting fee",
    "currency": "EUR",
    "autoDelivery": true,
    "customer": {
      "faktooraCustomerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    "invoiceItems": [
      {
        "description": "Web hosting — Standard plan",
        "quantity": 1,
        "unitPrice": 49.90,
        "vatRate": 19
      }
    ],
    "deliveryEmail": {
      "to": "billing@customer.example.com",
      "subject": "Your monthly hosting invoice"
    }
  }' \
  https://api.faktoora.com/api/v1/recurring-invoice

Response (201)

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Monthly hosting fee",
  "frequency": "monthly",
  "nthDay": 1,
  "monthOffset": null,
  "startDate": "2025-02-01T00:00:00.000Z",
  "endDate": null,
  "status": "active",
  "autoDelivery": true,
  "nextExecutionDate": "2025-02-01T00:00:00.000Z",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "template": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "subject": null,
    "currency": "EUR",
    "amount": 49.90,
    "customer": {
      "name": "Acme GmbH",
      "firstName": null,
      "lastName": null,
      "email": "billing@customer.example.com",
      "country": "DE"
    }
  }
}

Example: Create a quarterly schedule with month offset

curl -X POST \
  -H "X-API-KEY: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "frequency": "quarterly",
    "nthDay": 15,
    "monthOffset": 2,
    "startDate": "2025-01-01T00:00:00.000Z",
    "endDate": "2026-12-31T00:00:00.000Z",
    "name": "Quarterly license fee",
    "currency": "EUR"
  }' \
  https://api.faktoora.com/api/v1/recurring-invoice

This creates invoices on the 15th of the 3rd month of each quarter (March, June, September, December) because monthOffset: 2 offsets by 2 months from the quarter start.

Example: Create a schedule with custom dates

curl -X POST \
  -H "X-API-KEY: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "frequency": "custom",
    "customDates": [
      "2025-03-15T00:00:00.000Z",
      "2025-06-30T00:00:00.000Z",
      "2025-12-01T00:00:00.000Z"
    ],
    "name": "Project milestone invoices",
    "currency": "EUR"
  }' \
  https://api.faktoora.com/api/v1/recurring-invoice

Example: List active schedules

curl -H "X-API-KEY: your-api-token" \
  "https://api.faktoora.com/api/v1/recurring-invoices?status[]=active&sort=createdAt&order=desc&limit=10"

Response (200)

{
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Monthly hosting fee",
      "frequency": "monthly",
      "status": "active",
      "nextExecutionDate": "2025-03-01T00:00:00.000Z",
      "template": { "id": "...", "currency": "EUR", "amount": 49.90, "customer": null }
    }
  ],
  "meta": {
    "offset": 0,
    "limit": 10,
    "total": 1,
    "pages": 1
  }
}

Example: Pause a schedule

curl -X PATCH \
  -H "X-API-KEY: your-api-token" \
  https://api.faktoora.com/api/v1/recurring-invoice/f47ac10b-58cc-4372-a567-0e02b2c3d479/paused

Example: Update schedule template fields

curl -X PATCH \
  -H "X-API-KEY: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated monthly fee",
    "invoiceItems": [
      {
        "description": "Web hosting — Premium plan",
        "quantity": 1,
        "unitPrice": 79.90,
        "vatRate": 19
      }
    ]
  }' \
  https://api.faktoora.com/api/v1/recurring-invoice/f47ac10b-58cc-4372-a567-0e02b2c3d479

Unspecified fields are preserved. To clear a field, set it to null.