POST

Create a credit note

Scope: sales:invoices.write https://api.alladdin.com/api/v2/credit-notes

Creates a new credit note for a contact. Credit notes reduce the balance owed by a customer — typically issued to correct an error, apply a discount, or cancel a previously issued invoice.
You must provide a contact_id referring to an existing contact. Include line items in the items array. The response returns the new credit note id.

Request body

Do not reuse an active numbering series format

Do not send number with a value that follows the format of an existing numbering series. The series keeps its own counter and ignores manually assigned numbers. If a series is at number 24 and you create a document manually with 27, the series will keep issuing 25 and 26, and when it reaches 27 it will try to create a number that already exists: the request will fail and you will have lost the correlativity and the order of the series. If you need custom numbering, use a prefix or a format that does not match any active series, or manage every document in that series with number_line_id.

object contact_id string required

Identifier of an existing contact

contact_name string optional

Name of the contact

description string | null optional

Free-text description

date string<date> optional

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 optional

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 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 credit note

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

items[] object[] required

Line items to include

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 title 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

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.

Whether this line is a supply expense (suplido) paid on behalf of the client. Excluded from the tax base.

tags[] string[] optional

Tags to attach

custom_fields[] object[] optional

Custom field values

field string

Custom field identifier

value string

Value stored in the custom field

number string | null optional

Custom document number. Use only if you do not want to assign the number via one of the numbering series created in Alladdin (e.g. to replicate exactly the number from another platform). The value is saved as-is, without correlativity validation. If this field is sent, number_line_id is ignored.
Warning: do not use a value that matches the format of an existing numbering series. The series keeps its own counter regardless of manually assigned numbers -- e.g. if a series is at number 24 and you manually create a document with 27, the series will keep issuing 25, 26, and when it reaches 27 it will try to create a number that already exists: the request will fail and the series will have lost its correlativity and order. If you need custom numbering, use a prefix or format that does not match any active series, or manage every document in that series with number_line_id.

number_line_id string | null optional

Identifier of the numbering series used to automatically assign the next correlative number. This is the recommended option, as it preserves the document order and correlativity. If both fields are sent, number takes priority and number_line_id is ignored.

warehouse_id string | null optional

Identifier of the warehouse

sales_channel_id string | null optional

Identifier of the sales channel

discount number | null optional

Global discount percentage

payment_method_id string | null optional

Identifier of the default payment method

design_id string | null optional

Identifier of the design template to apply to the document

shipping_address object | null optional

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

python

import requests

url = "https://api.alladdin.com/api/v2/credit-notes"
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",
    "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"
            ],
            "sku": "string",
            "account": "string",
            "project_id": "string",
            "unit_type": "string",
            "supplied": false
        }
    ],
    "tags": [
        "string"
    ],
    "custom_fields": [
        {
            "field": "string",
            "value": "string"
        }
    ],
    "number": "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.post(url, headers=headers, json=payload)
print(response.json())

Responses

Response

json

{
  "id": "507f1f77bcf86cd799439011"
}

Success responses

201 Credit note 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 429 Rate limit exceeded application/json 500 Internal server error application/json object type string title string status integer detail string

Next →Create a payment for a credit note →