Update an invoice
Scope: sales:invoices.write https://api.alladdin.com/api/v2/invoices/{invoiceId}
Replaces all mutable fields of an existing invoice. This is a full replacement — any field you omit from the request body will be reset to its default value.
To avoid accidentally clearing data, first fetch the invoice with GET, modify the fields you need, and send back the full object. Partial updates are not supported. Updating an invoice does not affect payments already recorded against it.
Parameters
Path parameters
invoiceId string required
Invoice ID (24-char hex ObjectId)
Request body
object contact_id string
Identifier of an existing contact
contact_name string
Name of the contact
description string | null
Free-text description of the invoice
date string<date>
Issue date in ISO 8601 format. Accepts date (YYYY-MM-DD) or datetime (e.g. 2026-01-15T00:00:00+00:00)
due_date string<date> | null
Payment due date in ISO 8601 format. Accepts date (YYYY-MM-DD) or datetime (e.g. 2026-01-15T00:00:00+00:00)
notes string | null
Internal notes visible only to your team
body string | null
Rich-text content printed on the invoice
language string | null
ISO 639-1 language code for the invoice
currency string | null
ISO 4217 currency code
currency_change number<float> | null
Exchange rate to apply when the currency differs from your account currency
items[] object[]
Line items to include in the 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.
service_id string | null
Service identifier. When provided, the line type is automatically set to "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 weight number | null cost_price number | null
Unit cost price for margin calculations
account string | null project_id string | null unit_type string | null supplied boolean | null
Whether this line is a supply expense (suplido) paid on behalf of the client. Excluded from the tax base.
retention number | null
IRPF withholding percentage to apply to this line. Reduces the invoice total.
tags[] string[]
Tags to attach to the invoice
custom_fields[] object[]
Custom field values to set on the invoice
field string
Custom field identifier
value string
Value stored in the custom field
number_line_id string | null
Identifier of the numbering series to use
warehouse_id string | null
Identifier of the warehouse for stock movements
sales_channel_id string | null
Identifier of the sales channel
discount number | null
Global discount percentage to apply
payment_method_id string | null
Identifier of the default payment method
design_id string | null
Identifier of the design template to apply to the document
shipping_address object | null
Structured shipping address. Omit to leave unchanged (update) or unset (create). Pass null to clear it. The address fields (name, address_line_1, city, ...) are only used with type=manual; with billing, hidden or contact they are ignored. Use type=contact with contact_address_id to point to an address saved on the contact.
type string required
Address mode: manual (uses the address fields), billing (the billing address of the contact), hidden (no address displayed) or contact (an address saved on the contact, requires contact_address_id)
Enum: billing hidden manual contact name string | null optional
Name of the shipping recipient (the given name when family_name is also sent)
family_name string | null optional
Family name of the shipping recipient
organization string | null optional
Company or organization of the shipping recipient
address_line_1 string | null optional
Primary address line
address_line_2 string | null optional
Secondary address line
city string | null optional
City or locality
postal_code string | null optional
Postal or ZIP code
province string | null optional
State, province, or region
country string | null optional
Country name
country_code string | null optional
ISO 3166-1 alpha-2 country code
email string | null optional
Contact email for shipping
phone string | null optional
Contact phone number for shipping
mobile string | null optional
Mobile number for shipping
contact_address_id string | null optional
Identifier of an address saved on the contact (shipping_id in the contact shipping_addresses). Required when type is contact
Request
import requests
url = "https://api.alladdin.com/api/v2/invoices/{invoiceId}"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Accept": "application/json",
}
payload = {
"contact_id": "string",
"contact_name": "string",
"description": "string",
"date": "2026-01-15",
"due_date": "2026-01-31",
"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",
"weight": 0,
"cost_price": 0,
"account": "string",
"project_id": "string",
"unit_type": "string",
"supplied": false,
"retention": 0
}
],
"tags": [
"string"
],
"custom_fields": [
{
"field": "string",
"value": "string"
}
],
"number_line_id": "string",
"warehouse_id": "string",
"sales_channel_id": "string",
"discount": 0,
"payment_method_id": "string",
"design_id": "string",
"shipping_address": {
"type": "manual",
"name": "string",
"family_name": "string",
"organization": "string",
"address_line_1": "string",
"address_line_2": "string",
"city": "string",
"postal_code": "string",
"province": "string",
"country": "string",
"country_code": "ES",
"email": "string",
"phone": "string",
"mobile": "string",
"contact_address_id": "string"
}
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())Responses
Response
{
"id": "string"
}Success responses
200 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 Invoice not found application/json 429 Rate limit exceeded application/json