Design
File operations
Append PDF files and other templates to the generated PDF, or attach files inside it, with one tag in your template.
ENTERPRISE FEATURE
Available for:
Carbone Cloud
Carbone On-premise
Embedded Carbone JS
v4.23.0+
Overview
Available operations:
- appendFile: Append PDF files at the end of the generated document.
- appendTemplate: Append another Carbone template to the generated document. Carbone renders the nested template (as PDF) and appends the result.
- attachFile: Attach an external file inside a PDF (e.g., XML for Factur-X and ZUGFeRD).
Supports files as URL or Data-URI (Base64 encoded)
Compatible with generated PDF files.
For the Cloud API: maxDownloadFileSizeTotal = 50MB and maxDownloadFileCount = 40
Get inspired by one of our real-life examples: Quote With Datasheet
:appendFile(where)
v4.22.0+
Append an external file inside the generated document
Only PDF files can be added at the end of the current generated document.
If the generated file is not a PDF, the command is ignored.
Carbone will return an error and will not generate the report in the following scenarios:
- If the provided URL returns an error (2 retries for Carbone Cloud).
- If the downloaded document is not recognized as a valid PDF.
- If more than
maxDownloadFileCountfiles are to be downloaded - If the total size of all downloaded files exceeds
maxDownloadFileSizeTotalMB.
Carbone will ignore the formatter and proceed to generate the report in the following cases: - If the provided URL is null, undefined, or an empty string.
- If the final report is not in PDF format
| Params | Description | Type |
|---|---|---|
| where | Position to insert the document: "start" (beginning) or "end" (default). | String |
Example: append datasheets to a quote
To append one PDF per item, write the tag in a loop. In this quote, {d.products[i].datasheet:appendFile} sits next to each model in the datasheets list. The tag prints nothing. Carbone appends each datasheet after the quote, in the order of the loop.
{
"id": "Q-2026-0187",
"date": "2026-11-10",
"customer": "Acme Corporation",
"products": [
{
"name": "Solar panel 425 W",
"model": "DS425-108M10T-03",
"quantity": 24,
"unitPrice": 189,
"amount": 4536,
"datasheet": "https://carbone.io/examples/quote-with-datasheet/dualsun-a4-technical-drawing-425w.pdf"
},
{
"name": "Solar panel 500 W",
"model": "DS500-120M10TB-03",
"quantity": 16,
"unitPrice": 229,
"amount": 3664,
"datasheet": "https://carbone.io/examples/quote-with-datasheet/dualsun-a3-technical-drawing-500w.pdf"
}
],
"total": 8200
}
Text of template.docx
QUOTE
{d.customer}
Quote {d.id} · {d.date:formatD(LL)}
PRODUCT
AMOUNT
{d.products[i].name}
{d.products[i].quantity} × {d.products[i].unitPrice:formatC}
{d.products[i].amount:formatC}
{d.products[i+1].name}
Total
{d.total:formatC}
DATASHEETS
{d.products[i].name}
{d.products[i].model} {d.products[i].datasheet:appendFile}
{d.products[i+1].name}
The datasheets follow this page.



Each appended page keeps its own size and orientation. Page 2 is A4 landscape and page 3 is A3 landscape, both shown at the same reduced scale.
Render the report with "convertTo": "pdf". Other output formats ignore the tag.
For a step-by-step guide, see the Quote With Datasheet example.
:appendTemplate(templateOrVersionId, position)
v5.0.3+
Append an external template inside the generated document.
Sends part of the data to the injected template. Carbone generates the document
(automatically in PDF) and appends it to the current template.
It can be used to append a template in a loop.
The following options are automatically passed to the injected template:
lang, currency, enum, converter, translations, and complement.
Carbone will return an error and will not generate the report in the following cases:
- If the injected template returns an error during generation.
- If more than
maxDownloadFileCountfiles are injected. - If the total size of all injected files exceeds
maxDownloadFileSizeTotalMB.
Carbone will ignore the formatter and generate the report normally in the following cases:
- If the data passed to the formatter is null, undefined, or an empty string.
- If the final report is not in PDF format. Only PDF files can be appended.
Beta feature: This feature is available only for the Carbone On-Premise version.
| Params | Description | Type |
|---|---|---|
| templateOrVersionId | The template ID or version ID to append. | String |
| position | Position where the document is inserted: "start" (beginning) or "end" (default). | String |
Example: append one invoice per order
Use :appendTemplate when each item in your data should produce its own rendered document, and the final PDF is the concatenation of all of them. Carbone renders each nested template in parallel and appends them to the main report in loop order. This is useful for cover pages, per-recipient deliverables, or PDFs of up to 20,000 pages built from many small parallelized renders.
PDF output only. :appendTemplate works only when the final report is generated as a PDF. If the output format is anything else (DOCX, XLSX, ODT, …), the formatter is silently ignored and the main report is rendered without the appended content.
Store the nested template first, then pass its template ID (renders the latest deployed version) or version ID (pins a specific version). Both are returned by the upload-a-template API and visible in Carbone Studio.
Here a billing summary loops over orders in one paragraph: {d.orders[i]:appendTemplate(1550932030872181245)}{d.orders[i+1]}. The tag prints nothing. Each order is rendered through invoice.docx and appended after the summary, in loop order.
{
"period": "October 2026",
"orders": [
{ "orderId": "A-1001", "customer": "Acme Corp", "amount": 2400 },
{ "orderId": "A-1002", "customer": "Globex", "amount": 980 },
{ "orderId": "A-1003", "customer": "Initech Labs", "amount": 5120 }
],
"total": 8500
}

Text of template.docx
BILLING SUMMARY
{d.period}
One invoice per order follows this page
INVOICE
AMOUNT
{d.orders[i].customer}
{d.orders[i].orderId}
{d.orders[i].amount:formatC}
{d.orders[i+1].customer}
Total
{d.total:formatC}
{d.orders[i]:appendTemplate(1550932030872181245)}{d.orders[i+1]}




The nested template receives each orders[i] object as its own {d}: write {d.orderId}, {d.customer}, {d.amount} directly. These options of the main render are forwarded to every nested render: lang, timezone, the currency options (currencySource, currencyTarget, currencyRates), converter, enum, translations, complement.
To run the example, upload invoice.docx and replace 1550932030872181245 in the main template with its template ID.
Position
Pass 'start' as the second argument to prepend the nested document instead of appending it: {d:appendTemplate(110212, 'start')}.
Limits
- No nesting: an appended template cannot use
:appendTemplateitself, even if it appends a different template. The render fails withCircular dependency detected in appendTemplate formatter. - Time limit: each appended template, and each style template set with
o.styleSource, has its own download time limit (maxDownloadFileTimeoutOn-Premise). When it is reached, the error isTime limit reached (max <ms> ms, maxDownloadFileTimeout).
:attachFile(name, type)
v4.23.0+
Attach an external file inside the generated document
File attachment is a special feature of PDFs. It can be used for example to add Factur-X XML information
If the generated file is not a PDF, the command is ignored.
Carbone will return an error and will not generate the report in the following scenarios:
- If the provided URL returns an error (2 retries for Carbone Cloud).
- If the downloaded document is not recognized as a valid PDF.
- If more than
maxDownloadFileCountfiles are to be downloaded - If the total size of all downloaded files exceeds
maxDownloadFileSizeTotalMB
Carbone will ignore the formatter and proceed to generate the report in the following cases: - If the provided URL is null, undefined, or an empty string.
- If the final report is not in PDF format
| Params | Description | Type |
|---|---|---|
| name | file name | String |
| type | attachment type AFRelationship. Can be "Source", "Data" (by default), "Alternative", "Supplement", "Unspecified", "FormData", "Schema". | String |
Example: attach Factur-X and ZUGFeRD invoice data
Step-by-step guide to create a real-life template: Factur-X Invoice Automation