Create a recurring invoice
sales:invoices.writehttps://api.holded.com/api/v2/recurring-invoicesCreates a new recurring invoice template. A recurring invoice automatically generates invoices at the specified interval. You must provide a `contact_id`, `items`, and a `periodicity` value. The `periodicity` controls how often invoices are generated (e.g. `monthly`, `yearly`). The response returns the new recurring invoice `id`.
Request body
Identifier of an existing contact
Name of the contact
Recurrence interval. Accepted values: `daily` (d), `weekly` (w), `biweekly` (bw), `monthly` (m), `bimonthly` (bm), `quarterly` (q), `half-yearly` (ba), `yearly` (a)
Whether to automatically convert occurrences into invoices
falseNumber of days after the invoice date that payment is due
Day of the month on which the contact pays
Date on which the recurrence ends (inclusive). ISO 8601 format (YYYY-MM-DD)
Free-text description
Start date / first invoice date. ISO 8601 format (YYYY-MM-DD)
Internal notes visible only to your team
When true, a line with no taxes of its own, not linked to a catalog product or service, for a contact without default taxes takes the account's default taxes: its sales taxes on a sales document, its purchases taxes on a purchase document. When false or omitted, such a line is created untaxed.
falseRich-text content printed on the generated invoices
ISO 639-1 language code
ISO 4217 currency code
Exchange rate when currency differs from account currency
Line items for the recurring invoice
Kind of line. `product` and `service` are billable lines whose amount (`units` × `price`, less `discount`, plus `taxes`) is added to the document total. `title` is a section-header line that shows only its `name` and carries no amount — it does not contribute to the total. Other values are special-purpose lines. Omit this field for an ordinary priced line item.
productservicetitleIdentifier of an existing catalog product to link this line to. The id is stored as a reference associating the line with the product (used for stock and reporting). Each line field (`price`, `taxes`, ...) is taken as sent; api2 stores the line values you provide and does not itself read them back from the product record. Leave unset for a free-text line that is not a catalog product.
Identifier of the variant of `product_id` to link this line to. Requires `product_id`. Leave unset for a line without variant.
Identifier of an existing catalog service to link this line to. When provided, the line type is automatically set to `service`. Leave unset for a free-text line that is not a catalog service.
Tax keys applied to this line. When omitted, the contact default tax applies, or, if the contact has none, the account default tax when the request asks for it, else no tax.
Tags to attach
Identifier of the numbering series to use
Global discount percentage
Identifier of the design template to apply to the document
Request
import requests
url = "https://api.holded.com/api/v2/recurring-invoices"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Accept": "application/json",
}
payload = {
"contact_id": "string",
"contact_name": "string",
"periodicity": "monthly",
"convert_automatically": false,
"due_days": 0,
"contact_payment_day": 0,
"end_date": "2024-01-15",
"description": "string",
"date": "2026-01-01",
"notes": "string",
"default_taxes": false,
"body": "string",
"language": "es",
"currency": "EUR",
"currency_change": 0,
"items": [
{
"name": "string",
"type": "product",
"description": "string",
"product_id": "string",
"variant_id": "string",
"service_id": "string",
"units": 0,
"price": 0,
"discount": 0,
"taxes": [
"s_iva_21"
],
"tags": [
"string"
],
"sku": "string",
"account": "string",
"project_id": "string"
}
],
"tags": [
"string"
],
"number_line_id": "string",
"discount": 0,
"design_id": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())Responses
Response
{
"id": "507f1f77bcf86cd799439011"
}Success responses
201Recurring invoice createdapplication/jsonError responses
400Bad requestapplication/json401Invalid or missing API keyapplication/json403Insufficient permissionsapplication/json422Validation errorapplication/json