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:

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:

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.

data.jsonDownload
{
  "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
}
template.docxDownload
DOCX template of a quote with the appendFile tag in the loop of the datasheets list

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.

report.pdfDownload
PDF generated by Carbone: an A4 portrait quote, then the appended A4 landscape and A3 landscape datasheets
report.pdf · Page 2
PDF generated by Carbone: an A4 portrait quote, then the appended A4 landscape and A3 landscape datasheets, Page 2
report.pdf · Page 3
PDF generated by Carbone: an A4 portrait quote, then the appended A4 landscape and A3 landscape datasheets, Page 3

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:

Carbone will ignore the formatter and generate the report normally in the following cases:

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.

data.jsonDownload
{
  "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
}
template.docxDownload
DOCX templates of a billing summary that appends the nested invoice template once per order
invoice.docxDownload
DOCX templates of a billing summary that appends the nested invoice template once per order, invoice.docx

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

report.pdfDownload
PDF generated by Carbone: the billing summary, then one appended invoice per order
report.pdf · Page 2
PDF generated by Carbone: the billing summary, then one appended invoice per order, Page 2
report.pdf · Page 3
PDF generated by Carbone: the billing summary, then one appended invoice per order, Page 3
report.pdf · Page 4
PDF generated by Carbone: the billing summary, then one appended invoice per order, Page 4

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

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

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