From dc712624a0be22a405de2566a9ce528a7fd30076 Mon Sep 17 00:00:00 2001
From: Reshma Bidikar <85998496+reshmabidikar@users.noreply.github.com>
Date: Fri, 21 Aug 2026 11:30:19 +0530
Subject: [PATCH] document additional invoice template fields

---
 userguide/tutorials/invoice_templates.adoc | 202 +++++++++++++++++++++
 1 file changed, 202 insertions(+)

diff --git a/userguide/tutorials/invoice_templates.adoc b/userguide/tutorials/invoice_templates.adoc
index 777a9cc7a..d819b60bd 100644
--- a/userguide/tutorials/invoice_templates.adoc
+++ b/userguide/tutorials/invoice_templates.adoc
@@ -495,6 +495,208 @@ curl -v \
      http://127.0.0.1:8080/1.0/kb/tenants/userKeyValue/LOGO_INFO
 ----
 
+== Invoice Template Fields Reference
+
+In addition to the `company`, `logo`, `brand`, and `text` (translation) fields covered above, you can use some additional fields in the template. This section lists those fields.
+
+=== Invoice Fields
+
+These fields are accessed under the `invoice.` namespace, e.g. `{{invoice.chargedAmount}}`.
+
+For example, to use the `chargedAmount` field in the template, you can use the following snippet:
+
+[source,html]
+----
+Invoice Amount Charged: #{{invoice.chargedAmount}}
+----
+
+The table below lists all the available invoice fields.
+
+[cols="1,3", options="header"]
+|===
+| Field | Description
+
+| `invoiceNumber`| The invoice number
+
+| `invoiceItems`| The list of invoice items on this invoice (see <<Invoice Item Fields>> below). Iterate with `{{#invoice.invoiceItems}}...{{/invoice.invoiceItems}}`.
+
+| `trackingIds`| Tracking IDs associated with the invoice
+
+| `chargedAmount`| Total charged amount on the invoice
+
+| `originalChargedAmount`| Charged amount before any adjustments
+
+| `balance`| Remaining balance on the invoice
+
+| `formattedChargedAmount`| Charged amount, formatted per the account locale and invoice currency
+
+| `formattedPaidAmount`| Paid amount, formatted per the account locale and invoice currency
+
+| `formattedBalance`| Balance, formatted per the account locale and invoice currency
+
+| `processedCurrency`| Currency the payment was processed in, if different from the invoice currency; `null` otherwise
+
+| `processedPaymentRate`| Conversion rate used, if the payment was processed in a different currency; `null` otherwise
+
+| `migrationInvoice`| Whether this is a migration invoice
+
+| `invoiceDate`| Invoice date
+
+| `targetDate`| Target date used to generate the invoice
+
+| `currency`| Invoice currency
+
+| `paidAmount`| Amount paid against this invoice
+
+| `formattedInvoiceDate`| Invoice date, formatted per the account locale
+
+| `id`| Invoice ID
+
+| `createdDate`| Invoice creation timestamp
+
+| `updatedDate`| Invoice last-updated timestamp
+
+| `status`| Invoice status
+
+| `parentInvoice`| Whether this is a parent invoice
+
+| `parentAccountId`| Parent account ID, for child invoices
+
+| `parentInvoiceId`| Parent invoice ID, for child invoices
+
+| `groupId`| Group ID associated with the invoice, if any
+
+| `creditedAmount`| Amount credited against this invoice
+
+| `refundedAmount`| Amount refunded against this invoice
+|===
+
+
+=== Invoice Item Fields
+
+These fields are accessible within an `{{#invoice.invoiceItems}}...{{/invoice.invoiceItems}}` block. For example to use the invoice item `prettyPlanName` and `formattedAmount` fields, you can use the following snippet:
+
+[source,html]
+----
+{{#invoice.invoiceItems}}
+    {{prettyPlanName}}: {{formattedAmount}}
+{{/invoice.invoiceItems}}
+----
+
+The table below lists all the available invoice item fields.
+
+[cols="1,3", options="header"]
+|===
+| Field | Description
+
+| `amount`| Item amount
+
+| `currency`| Item currency
+
+| `formattedAmount`| Item amount, formatted per the account locale and invoice currency
+
+| `invoiceItemType`| Item type (e.g. recurring, fixed, usage, tax, credit)
+
+| `description`| Item description (translated, if a matching resource bundle entry exists)
+
+| `startDate`| Item service period start date
+
+| `endDate`| Item service period end date
+
+| `formattedStartDate`| Start date, formatted per the account locale
+
+| `formattedEndDate`| End date, formatted per the account locale
+
+| `invoiceId`| ID of the invoice this item belongs to
+
+| `accountId`| Account ID
+
+| `childAccountId`| Child account ID, for items billed to a child account
+
+| `bundleId`| Bundle ID associated with the item
+
+| `subscriptionId`| Subscription ID associated with the item
+
+| `productName`| Product name (translated)
+
+| `prettyProductName`| Human-readable product name (translated)
+
+| `planName`| Plan name (translated)
+
+| `prettyPlanName`| Human-readable plan name (translated)
+
+| `phaseName`| Phase name (translated)
+
+| `prettyPhaseName`| Human-readable phase name (translated)
+
+| `usageName`| Usage unit name (translated)
+
+| `prettyUsageName`| Human-readable usage unit name (translated)
+
+| `id`| Item ID
+
+| `createdDate`| Item creation timestamp
+
+| `updatedDate`| Item last-updated timestamp
+
+| `quantity`| Item quantity
+
+| `itemDetails`| Free-form item details, if set
+
+| `catalogEffectiveDate`| Catalog effective date used to price this item
+|===
+
+=== Account Fields
+
+These fields are accessed under the account. namespace, e.g. {{account.name}}, and come directly from the account object (rather than a formatter wrapper) — so, unlike the invoice and invoice item fields above, there are no formatted*/pretty* convenience variants.
+
+[cols="1,3", options="header"]
+|===
+| Field | Description
+
+| externalKey| The account's external key
+
+| name| The account name (first and last name combined, where applicable)
+
+| firstNameLength| The length of the first name that can be extracted from name
+
+| email| The primary account email
+
+| billCycleDayLocal| The bill cycle day for the account, interpreted in the account's timezone
+
+| currency| The account's currency
+
+| paymentMethodId| The ID of the account's current default payment method
+
+| referenceTime| The reference time for the account
+
+| timeZone| The account's timezone
+
+| locale| The account's locale
+
+| address1| Address line 1
+
+| address2| Address line 2
+
+| companyName| The company name for the account
+
+| city| City
+
+| stateOrProvince| State or province
+
+| postalCode| Postal code
+
+| country| Country
+
+| phone| Phone number
+
+| migrated| Whether the account was migrated into the system
+
+| parentAccountId| The ID of the parent account, if any
+
+| paymentDelegatedToParent| Whether the child account's payments are delegated to the parent account
+|===
+
 == Testing Your Changes
 
 No matter how you configure your template, translations, or branding, you'll want to confirm the changes render as expected before using them in production.