Scope: sales:invoices.write https://api.alladdin.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_id string required

Identifier of an existing contact

contact_name string optional

Name of the contact

periodicity string required

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

convert_automatically boolean optional

Whether to automatically convert occurrences into invoices

default: false due_days integer | null optional

Number of days after the invoice date that payment is due

contact_payment_day integer | null optional

Day of the month on which the contact pays

end_date string<date> | null optional

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

description string | null optional

Free-text description

date string<date> optional

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

notes string | null optional

Internal notes visible only to your team

default_taxes boolean optional

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 body string | null optional

Rich-text content printed on the generated invoices

language string | null optional

ISO 639-1 language code

currency string | null optional

ISO 4217 currency code

currency_change number<float> | null optional

Exchange rate when currency differs from account currency

items[] object[] required

Line items for the recurring invoice

name string type string | 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: product service title `` description string | null product_id string | 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_id string | null

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

service_id string | 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.

units number | null price number | null discount number | 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 sku string | null account string | null project_id string | null tags[] string[] optional

Tags to attach

number_line_id string | null optional

Identifier of the numbering series to use

discount number | null optional

Global discount percentage

design_id string | null optional

Identifier of the design template to apply to the document

Request

import requests

url = "https://api.alladdin.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

201 Recurring invoice created application/json object id string

Error responses

400 Bad request application/json 401 Invalid or missing API key application/json 403 Insufficient permissions application/json 422 Validation error application/json

Next →Skip a recurring invoice occurrence →