Skip to main content
POST

Create a recurring invoice

Scope:sales:invoices.write
https://api.holded.com/api/v2/recurring-invoices

Creates 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

object
contact_idstringrequired

Identifier of an existing contact

contact_namestringoptional

Name of the contact

periodicitystringrequired

Recurrence interval. Accepted values: `daily` (d), `weekly` (w), `biweekly` (bw), `monthly` (m), `bimonthly` (bm), `quarterly` (q), `half-yearly` (ba), `yearly` (a)

convert_automaticallybooleanoptional

Whether to automatically convert occurrences into invoices

default: false
due_daysinteger | nulloptional

Number of days after the invoice date that payment is due

contact_payment_dayinteger | nulloptional

Day of the month on which the contact pays

end_datestring<date> | nulloptional

Date on which the recurrence ends (inclusive). ISO 8601 format (YYYY-MM-DD)

descriptionstring | nulloptional

Free-text description

datestring<date>optional

Start date / first invoice date. ISO 8601 format (YYYY-MM-DD)

notesstring | nulloptional

Internal notes visible only to your team

default_taxesbooleanoptional

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.

default: false
bodystring | nulloptional

Rich-text content printed on the generated invoices

languagestring | nulloptional

ISO 639-1 language code

currencystring | nulloptional

ISO 4217 currency code

currency_changenumber<float> | nulloptional

Exchange rate when currency differs from account currency

items[]object[]required

Line items for the recurring invoice

namestring
typestring | null

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.

Enum:productservicetitle
descriptionstring | null
product_idstring | null

Identifier 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.

variant_idstring | null

Identifier of the variant of `product_id` to link this line to. Requires `product_id`. Leave unset for a line without variant.

service_idstring | null

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.

unitsnumber | null
pricenumber | null
discountnumber | null
taxes[]string[] | null

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[]string[] | null
skustring | null
accountstring | null
project_idstring | null
tags[]string[]optional

Tags to attach

number_line_idstring | nulloptional

Identifier of the numbering series to use

discountnumber | nulloptional

Global discount percentage

design_idstring | nulloptional

Identifier of the design template to apply to the document

Request

python
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

json
{
  "id": "507f1f77bcf86cd799439011"
}

Success responses

201Recurring invoice createdapplication/json
object
idstring

Error responses

400Bad requestapplication/json
401Invalid or missing API keyapplication/json
403Insufficient permissionsapplication/json
422Validation errorapplication/json