NetSuite transaction PDFs are only useful when they show the information people need to act. A packing slip that omits a customer-specific item code creates warehouse confusion. An invoice without a product reference, batch number, warranty detail, or configuration value sends customers back to your team for clarification.
The good news is that we do not need to redesign the entire transaction process to solve this problem. In most cases, we can add the required item fields directly to the transaction record layout through NetSuite’s Advanced PDF/HTML templates.
The important distinction is that NetSuite transactions contain more than one type of field. A transaction body field describes the document as a whole, while an item field belongs to an individual line. Adding the correct field requires understanding where the data lives, how NetSuite exposes it in the template, and whether the selected transaction form supports the desired output.
This guide explains how we approach item fields in NetSuite transaction PDFs, which field types belong in item tables, how to work with custom fields, and how to avoid the most common template errors.
Understand the Difference Between Transaction Body Fields and Item Fields
A NetSuite transaction has document-level information and line-level information.
Transaction body fields apply to the entire record. Examples include the customer name, transaction number, date, billing address, shipping address, sales representative, and payment terms. These values typically appear once in the header or summary area of an invoice, sales order, estimate, purchase order, or packing slip.
Item fields apply to a specific transaction line. Examples include the item name, description, quantity, rate, amount, units, location, tax code, and custom line details. These values belong inside the item table because each row can contain a different value.
| Field category | Examples | Appropriate PDF location |
|---|---|---|
| Transaction body | Customer, date, terms, shipping address | Header, footer, or summary |
| Item record | Item name, display name, manufacturer part number | Item table |
| Transaction line | Quantity, rate, location, custom column field | Item table |
| Transaction summary | Subtotal, tax, shipping, total | Summary section |
This distinction matters because placing an item-level value in the transaction header does not produce a reliable result. A transaction can contain dozens of items, and each row needs to render its own value.
We should first identify whether the requested field comes from the item record itself or from the transaction line. That answer determines the field ID, the template reference, and the best validation method.
What Item Information Can Appear on a NetSuite PDF?
NetSuite supports a wide range of item-related values in transaction templates. Standard fields are the most straightforward because NetSuite already makes them available through the item sublist.
Common examples include:
Item name or number
Display name
Description
Quantity
Units
Rate
Amount
Tax code
Location
Backordered quantity
Commitment status
Customer-specific item information, where configured
The exact fields available depend on the transaction type, account configuration, item type, customizations, and the form used to generate the document. An invoice does not necessarily expose exactly the same line values as a purchase order or fulfillment.
We also need to distinguish between information that is stored on the item record and information that is copied or entered on the transaction line. A product’s standard manufacturer part number might be stored on the item record. A customer’s requested configuration might exist only as a transaction column field. Both can appear in a PDF, but they are not interchangeable.
For complex requirements, we recommend documenting the desired output in a simple field map before editing the template. The map should identify the visible label, internal field ID, source record, transaction types, and the documents where the value must appear.
Use the Advanced PDF/HTML Template as the Presentation Layer
NetSuite’s Advanced PDF/HTML templates use HTML, CSS, and FreeMarker to control the appearance and content of generated documents. The template acts as the presentation layer. It determines where fields appear, how tables are structured, which sections display conditionally, and how the document behaves when values are missing.
For an item table, the relevant data is rendered inside the loop that processes transaction lines. A basic template commonly contains a structure similar to this:
<table>
<#list record.item as item>
<tr>
<td>${item.item}</td>
<td>${item.description}</td>
<td>${item.quantity}</td>
<td>${item.rate}</td>
<td>${item.amount}</td>
</tr>
</#list>
</table>The exact variable names differ between templates and account configurations, so we should not copy a field reference into production without validating it. The key principle is the placement: the item field belongs within the item loop and should use the current line object.
To add another column, we typically add a table header and a matching table cell. For example, a custom transaction column field could follow this general pattern:
<th>Customer Item Code</th><td>${item.custcol_customer_item_code}</td>The displayed label and the internal ID are separate. The label is what customers see. The internal ID is what the FreeMarker template uses to retrieve the value.
If the field is not a transaction column field, the reference will be different. An item record field and a custom line field might both look like item data to a business user, but NetSuite exposes them through different objects or IDs. We verify the source before selecting the syntax.
Adding a Standard Item Field
Standard item fields are the best place to start because they are generally available through NetSuite’s template field selector and standard transaction structure.
Our process is straightforward:
Open the relevant Advanced PDF/HTML template.
Locate the item table and the existing item loop.
Add a column heading where the new value should appear.
Add the corresponding FreeMarker field reference inside the line loop.
Save a copy of the template before testing.
Generate the PDF from a representative transaction.
The item table should remain readable after adding the field. A technically correct field that makes every description wrap across multiple pages is not a successful implementation. We consider column width, font size, line wrapping, alignment, and the difference between screen preview and PDF output.
For example, an item description should generally receive more horizontal space than a short unit code. Quantity and rate columns should remain narrow and aligned consistently. A long manufacturer part number may need wrapping or a smaller font, but reducing the entire document’s font size is rarely the best first response.
Adding a Custom Transaction Column Field
Custom transaction column fields are designed to store values at the line level. They are commonly used for details such as:
Customer item numbers
Project or job references
Product configuration values
Internal fulfillment instructions
Serial or batch-related information
Sales channel attributes
Line-specific compliance data
The internal ID for a custom column field generally begins with `custcol`, but we should confirm the exact ID in the field definition. A label such as “Customer SKU” does not tell us whether the field is a transaction column field, an item field, a sourced value, or a formula field.
Once confirmed, the field must be referenced in the correct item loop. A common pattern is:
${item.custcol_customer_sku}That syntax is illustrative. The actual field ID must match the account’s field definition, and the field must be available on the transaction and form being rendered.
A frequent implementation error is adding the custom field to the transaction form but not to the PDF template. Form visibility and PDF visibility are separate concerns. Another common issue is assuming that a field populated on one transaction type will automatically be present on another. Field sourcing, workflow behavior, scripts, and transaction conversion rules all affect whether the value reaches the final record.
We should test both the source transaction and any downstream transactions that use the template. A value that appears on a sales order may not appear on the invoice if the field is not copied forward.
NetSuite workflows are one way to populate transaction fields according to business rules. We cover related automation concepts in our guide to using NetSuite workflows to auto-populate fields based on transaction dates.
Adding Fields From the Item Record
An item record field describes the product rather than the specific transaction line. This distinction is essential when the business wants a product attribute printed on every document.
Examples include a manufacturer name, product family, country of origin, technical specification, or item-level compliance attribute. The value belongs to the item record and is then displayed for each transaction line associated with that item.
The correct field reference depends on how NetSuite exposes the item data in the template. We should use the template editor’s available field list, inspect a working item reference, and test the generated output. If the desired item field does not appear in the available fields, the problem is not solved by guessing a longer variable path.
Instead, we investigate whether:
The field is available on the item type used by the transaction.
The field is exposed to the selected transaction template.
The value is populated on the specific item record.
The transaction uses an item subtype with different available fields.
A custom transaction column field would be more appropriate.
A script or workflow needs to copy the value to the transaction line.
This approach prevents a common mistake, which is treating a missing template value as a formatting problem when the actual issue is data availability.
Use Conditional Logic for Optional Item Values
Not every item has the same attributes. A PDF template should not display empty labels, awkward blank columns, or the text `null` when a field is not populated.
FreeMarker conditional logic helps us control optional fields. A simple pattern looks like this:
<#if item.custcol_customer_sku?has_content>
<td>${item.custcol_customer_sku}</td>
<#else>
<td>Not provided</td>
</#if>Whether we show a fallback such as “Not provided” depends on the document’s purpose. A customer-facing invoice may look cleaner if the column is omitted or left blank. A warehouse document may require an explicit indicator when an operational value is missing.
Conditional logic also helps with item types that do not support the same attributes. A service item, inventory item, kit, assembly, and description item can produce different line data. The template should account for those differences rather than assuming every line has an identical structure.
When an entire column is optional, we need to decide whether to hide only the cell value or the whole column. Hiding individual values can leave an empty header and a visually confusing table. Hiding a whole column requires evaluating whether any line contains the field, which involves more advanced template logic and careful testing.
Formatting Item Fields for Real Documents
Adding a field is only one part of the work. The final PDF must remain usable for customers, accounting teams, warehouse staff, and other readers.
We pay close attention to the field’s data type. Text, dates, numbers, currencies, percentages, quantities, and references should not all be displayed the same way. A date might need a consistent regional format. A quantity may require a defined decimal precision. A currency field needs appropriate symbols and decimal handling.
Long values need special treatment. A product description can expand vertically, while a table column with a long code can create excessive horizontal width. We may need to set a specific width, allow wrapping, abbreviate the visible label, or move a secondary field to a detail section below the primary row.
We also consider the document’s page behavior. Adding a column can affect:
| Design concern | What we check |
|---|---|
| Width | Whether all columns fit within the printable area |
| Wrapping | Whether long values break cleanly instead of overlapping |
| Pagination | Whether headings repeat on additional pages |
| Alignment | Whether numbers and text remain easy to scan |
| Empty values | Whether blank fields create visual noise |
| Accessibility | Whether labels remain understandable in exported PDFs |
A PDF that looks acceptable with two short items is not fully tested. We need transactions with long descriptions, multiple pages, missing values, discounts, tax lines, kits, service items, and unusual quantities. Realistic data reveals issues that a simple preview does not.
Why an Item Field Might Display Blank
A blank field does not always mean the FreeMarker syntax is wrong. We troubleshoot the data path in order.
First, we confirm that the value exists on the transaction being rendered. The item record may contain the value, but the selected item on the transaction may be different. A custom line field may be visible on the form but empty on the specific test record.
Second, we confirm the field ID and field type. Internal IDs are case-sensitive in practice because a typo points to a different or nonexistent property. A body field referenced as a line field will not return the expected result.
Third, we verify the template context. A reference used inside the item loop is not the same as a reference used in the transaction header. The current line object must be available at the point where the field is called.
Fourth, we inspect permissions and form configuration. The user generating the PDF needs access to the relevant data, and the selected transaction form must expose or populate the field as expected.
The most useful troubleshooting sequence is:
Check the source record and confirm the value is populated.
Confirm the field’s internal ID and source type.
Test the field in the template’s available field list.
Place the reference inside the correct item loop.
Generate the PDF from a saved transaction, not only from preview.
Test with multiple item types and more than one transaction.
If the field still does not render, we consider whether a workflow, user event script, or sourced field should place the value directly on the transaction line. That approach is sometimes more stable than relying on a complex relationship at PDF-generation time.
Keep Data Automation Separate From PDF Design
PDF templates should control presentation. They should not become the primary place where business data is calculated, transformed, or repaired.
If a field requires complex logic, we prefer to populate and validate that value before the document is generated. A workflow can handle simple rules. A script may be appropriate for more involved transformations. An integration should deliver the required data consistently if the source is an external system.
This separation makes the system easier to maintain. It also helps when the same field is needed in saved searches, dashboards, analytics, integrations, and transaction PDFs. A field that exists only as a template calculation is difficult to reuse and difficult to audit.
For organizations moving custom and supplemental data into reporting environments, the data model matters beyond the PDF itself. Our article on transferring custom and supplemental fields to NetSuite Analytics Warehouse explains why custom field design should support downstream reporting as well as document output.
The same principle applies to custom transactions. If an organization has enabled custom transaction types, the fields, forms, templates, and automation should be reviewed together. Our guide to enabling support for custom transactions provides useful context for that broader configuration work.
Build a Repeatable Testing Process
A reliable PDF change requires more than checking whether one field appears. We use a defined test set that reflects the transaction’s actual business use.
The test should include a transaction with every target field populated, a transaction with optional fields blank, and a transaction with enough lines to create multiple pages. We also test long item names, long descriptions, different item types, discounts, tax, shipping, and any special transaction statuses that affect line visibility.
After the PDF renders, we verify both data and layout. The data review confirms that each row shows the correct value for the correct item. The layout review checks alignment, wrapping, page breaks, repeated headings, totals, and whitespace.
We also test the actual generation path. A PDF generated from a transaction record may behave differently from a preview generated in the template editor. If documents are emailed automatically, printed through a workflow, or generated by an external integration, those paths deserve validation too.
For organizations with more extensive automation requirements, our NetSuite automation and integration services can help connect field design, workflows, scripts, templates, and operational processes into one maintainable solution.
Common Design Decisions Before Going Live
Before publishing a template, we resolve several decisions with the business users. The first is whether the field belongs on every transaction or only on a specific document. An internal fulfillment instruction may not belong on a customer invoice. A customer item number may be essential on both the order confirmation and packing slip.
The second is whether the field should be editable on the transaction. If users need to override an item-level value for one order, a transaction column field is more appropriate than displaying a read-only item record field.
The third is whether the label will make sense to the audience. Internal field names rarely work as customer-facing labels. “Custcol reference 2” should become a meaningful phrase that explains the value.
The fourth is whether the field requires historical accuracy. If an item attribute changes after a transaction is created, the PDF might display the current item value rather than the value that existed when the transaction was entered, depending on how the field is sourced. For legal, fulfillment, or audit-sensitive information, copying the value to the transaction line at the appropriate point creates a more stable historical record.
These decisions prevent the template from becoming a patch for an unclear data model.
When to Bring in NetSuite Development Support
Simple column additions are manageable when the field is populated, exposed, and supported by the selected template. More complex situations deserve a structured technical review.
We recommend support when the PDF needs fields from multiple related records, conditional columns, custom transaction logic, line-level calculations, different outputs by subsidiary or customer, or consistent behavior across several transaction types. We also recommend support when a field appears correctly in NetSuite but fails in automated PDF generation.
A broader review is particularly valuable when documents are created from external order sources. Email-to-order workflows, payment integrations, inventory systems, and custom transaction processes all affect what data reaches the final PDF. Our article on turning customer emails into clean, automated NetSuite orders discusses the importance of clean transaction data before automation continues downstream.
The objective is not simply to make one PDF display one value. The objective is to create a dependable flow from source data, to transaction record, to customer-facing document.
Conclusion
Adding item fields to NetSuite transaction PDFs is a practical way to improve document accuracy without rebuilding the transaction process. The work starts with identifying the data source, separating item record fields from transaction line fields, and placing the correct reference inside the item table loop.
From there, we focus on conditional display, formatting, permissions, downstream transaction behavior, and realistic PDF testing. We also keep data automation separate from presentation so that important values remain available for reporting, integrations, workflows, and future document requirements.
When a field is properly modeled and consistently populated, the PDF becomes a reliable extension of the transaction record. Customers receive clearer documents, warehouse teams get better fulfillment information, and internal users spend less time correcting avoidable omissions. If your templates, custom fields, and transaction automation need to work together, contact Versich to plan a maintainable NetSuite solution.
