Scope: sales:invoices.write https://api.alladdin.com/api/v2/documents/convert

Converts an existing document into a new document of a different type. For example, convert an estimate into an invoice or a sales order into a waybill.
The source document remains unchanged; a new document of the target type is created and linked to the source. Not all conversion pairs are supported — the available conversions depend on the document types configured in your account.
This is the only way to create a document that preserves the parent-child relationship with the source. For partial conversions (e.g. invoicing only a portion of a proforma), use this endpoint to create the linked document and then update the resulting document's line quantities or prices accordingly.

Request body

object source_type string required

Type of the source document to convert from

Enum: invoice creditnote estimate salesorder salesreceipt purchase order proform waybill source_id string required

Identifier of the source document

target_type string required

Type of the target document to convert to

Enum: invoice creditnote estimate salesorder salesreceipt purchase order proform waybill date string<date> | null optional

Issue date for the new document in ISO 8601 format

due_date string<date> | null optional

Due date for the new document in ISO 8601 format

number_line_id string | null optional

Identifier of the numbering series to use

description string | null optional

Description for the new document

notes string | null optional

Internal notes for the new document

draft boolean | null optional

Whether to create the new document as a draft

Request

import requests

url = "https://api.alladdin.com/api/v2/documents/convert"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json",
}

payload = {
    "source_type": "invoice",
    "source_id": "507f1f77bcf86cd799439011",
    "target_type": "invoice",
    "date": "2024-01-15",
    "due_date": "2024-02-15",
    "number_line_id": "string",
    "description": "string",
    "notes": "string",
    "draft": false
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

Responses

Response

{
  "id": "507f1f77bcf86cd799439011"
}

Success responses

201 Document converted 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 Source document not found application/json 422 Conversion not supported application/json 429 Rate limit exceeded application/json