PUT

Update a recurring invoice

Scope: sales:invoices.write https://api.alladdin.com/api/v2/recurring-invoices/{invoiceRecurringId}

Updates an existing recurring invoice, including its document fields (items, description, contact, date, tags, etc.) and its recurrence configuration (periodicity, convert_automatically, due_days, end_date, contact_payment_day).
This is a partial update — only the fields you include in the request body will be changed. Changing the recurrence configuration only affects future occurrences; invoices already generated are not modified.

Parameters

Path parameters

invoiceRecurringId string required

Recurring invoice ID (24-char hex ObjectId)

Request body

object contact_id string

Identifier of an existing contact

contact_name string

Name of the contact

periodicity string

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

convert_automatically boolean

Whether to automatically convert occurrences into invoices

due_days integer | null

Number of days after the invoice date that payment is due

contact_payment_day integer | null

Day of the month on which the contact pays

end_date string<date> | null

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

description string | null

Free-text description

date string<date>

Start date in ISO 8601 format (YYYY-MM-DD)

notes string | null

Internal notes visible only to your team

body string | null

Rich-text content printed on generated invoices

language string | null

ISO 639-1 language code

currency string | null

ISO 4217 currency code

currency_change number<float> | null

Exchange rate when currency differs from account currency

items[] object[]

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 shipping title rounding refund ecotax wrapping service `` 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.

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[]

Tags to attach

number_line_id string | null

Identifier of the numbering series to use

discount number | null

Global discount percentage

design_id string | null

Identifier of the design template to apply to the document

Request

python

import requests

url = "https://api.alladdin.com/api/v2/recurring-invoices/{invoiceRecurringId}"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json",
}

payload = {
    "contact_id": "string",
    "contact_name": "string",
    "periodicity": "string",
    "convert_automatically": false,
    "due_days": 0,
    "contact_payment_day": 0,
    "end_date": "2024-01-15",
    "description": "string",
    "date": "2026-01-01",
    "notes": "string",
    "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.put(url, headers=headers, json=payload)
print(response.json())

Responses

Response

json

{
  "id": "string"
}

Success responses

200 Recurring invoice updated 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 404 Recurring invoice not found application/json

← PreviousSkip a recurring invoice occurrence →

Next →List recurring invoices →

Alladdin