Sales Order and Purchase Order Liquid Form — Field Reference

Sales Order and Purchase Order Liquid Form — Field Reference

The Sales Order and Purchase Order custom forms are used to generate order PDFs. You can copy the default form and customize it using Liquid.

These forms use Order as the primary model. In every order template, the root object is:

{{ order }}

This applies to:

• Sales Order forms
• Purchase Order forms
• Requisition forms
• RMA Order forms
• Transfer Order forms

From order, you can access header fields, related objects, line items, custom fields, and — when Load Management is enabled — the related load.

---

Basic syntax

Read a field on the order:

{{ order.order_number }}
{{ order.order_date | format_date }}
{{ order.total }}

Loop order lines:

{% for item in order.order_items %}
  Line {{ item.order_item_seq_id }}: {{ item.description }} — Qty {{ item.quantity }}
{% endfor %}

Read a standard Versa custom field on the order:

{{ order | custom_field_by_name: 'Your Field Name' }}

Read a standard Versa custom field on a line:

{{ item | custom_field_by_name: 'Your Field Name' }}

---

Order header fields

These fields are available directly on order for both sales and purchase orders unless noted otherwise.

Field	Description	Example
id	Internal id of the order	{{ order.id }}
order_number	Sales or purchase order number	{{ order.order_number }}
order_date	Order date	{{ order.order_date | format_date }}
total	Order total including taxes and adjustments	{{ order.total }}
external_order_reference_number	Customer PO / external reference	{{ order.external_order_reference_number }}
internal_order_reference_number	Internal reference number	{{ order.internal_order_reference_number }}
message	Message or note on the order header	{{ order.message }}
order_item_subtotal_no_tax	Order subtotal before taxes	{{ order.order_item_subtotal_no_tax }}
order_item_applied_taxes	Taxes applied at line level	Loop as needed
total_taxes_array	Total taxes grouped by tax	Loop as needed
applied_taxes	Applied taxes on the order	Loop as needed
total_payment_amount	Total pre-payment received on the order	{{ order.total_payment_amount }}
total_weight	Total weight of products on the order	{{ order.total_weight }}
total_weight_unit	Unit for total weight	{{ order.total_weight_unit }}
blind_shipping	Blind shipping flag	{{ order.blind_shipping }}
is_rma_order?	Whether the order is an RMA order	{{ order.is_rma_order? }}
valid_from_date	Valid-from date where applicable	{{ order.valid_from_date | format_date }}
valid_to_date	Valid-to date where applicable	{{ order.valid_to_date | format_date }}
sales_order_freight_charge	Freight charge on the order	{{ order.sales_order_freight_charge }}
deposit_per_unit_amount	Deposit per unit amount	{{ order.deposit_per_unit_amount }}
quick_tag_names	Quick tag names on the order	{{ order.quick_tag_names }}

Sales-order-specific fields

Field	Description
customer_bill_to_id	Id of the customer on the sales order
customer_bill_to	Customer object. See customer_bill_to.
customer_ship_to	Customer ship-to record on the sales order
sales_agent	Sales agent on the order
related_invoices	Invoices created from this sales order
picklists	Picklists related to the order
unshipped_picklists	Picklists not yet fully shipped
route	Delivery route on the order. Example: {{ order.route.name }}

Purchase-order-specific fields

Field	Description
supplier	Supplier on the purchase order
supplier_id	Not directly exposed in Liquid; use order.supplier instead

---

Related objects on the order

Field	Description
term	Payment terms for the order
currency	Currency for the order. See currency.
ship_to_party	Ship-to party/address. See party.
ship_from_party	Ship-from party/address
contact_party	Contact party on the order
related_party	Related party on the order
firm	Company the order belongs to. See firm.
internal_organization	Entity the order belongs to. A firm can have many entities.
facility	Facility/warehouse the order ships from. Common fields: name, code
facility_id	Facility id
order_type	Order type object. Use order.order_type.description — values include sale, purchase, rma, transfer
order_type_id	Internal order type id
order_items	All line items on the order. See Order item fields below.
order_items_with_products_in_groups_by_2	Order items grouped for display
parent_order_items	Parent order items where applicable
public_custom_fields_list	Standard Versa custom fields on the order. See custom_field.
tags	Dimension tags on the order. See dimension tag and sample code.
shipping_preference	Shipping preference data for the order
docks	Dock assignments on the order
sorted_docks	Dock assignments in sorted order
related_unposted_shipment_packages	Related shipment packages not yet posted
freight_load	Load Management load linked to the order header for traceability. See Load Management fields below.

shipping_preference fields

When present, order.shipping_preference includes fields such as:

• shipping_carrier
• shipping_services
• package_width
• package_height
• package_depth
• package_dimension_units
• package_weight
• package_weight_units
• package_description
• country_of_manufacture
• shipping_service_description

---

Order item fields

Each line on the order is an order_item. In a loop, use item or your chosen variable name:

{% for item in order.order_items %}
  {{ item.order_item_seq_id }}
  {{ item.description }}
  {{ item.quantity }}
  {{ item.per_unit_cost }}
  {{ item.line_item_value }}
{% endfor %}

Field	Description
id	Internal id of the line
order	The parent order
order_item_seq_id	Line number
description	Line description
note_a	Note A on the line
note_b	Note B on the line
order_item_comment	Line comment
item_description	Same as Note A
per_unit_cost	Unit cost/price
quantity	Ordered quantity
quantity_shipped	Quantity shipped
quantity_outstanding	Ordered quantity minus shipped quantity
quantity_back_ordered	Back-ordered quantity
quantity_received	Quantity received
quantity_on_hand	Quantity on hand for the product in the order’s facility
quantity_available	Total quantity available for the product
quantity_on_purchase_order_outstanding	Outstanding PO quantity related to the line
line_item_value_before_adjustments	Line total before adjustments
line_item_value	Line total including adjustments, before taxes
order_item_adjustments	Discounts or surcharges on the line
order_item_applied_taxes	Taxes applied to the line
total_applied_tax	Total tax applied to the line
estimated_delivery_date	Estimated delivery date
ship_date	Ship date
product	Product on the line. See product.
related_product	Related product object
related_product_practical_name	Related product display name
item_product_number	Product number for the line
item_product_description	Product description for the line
measurement_unit	Measurement unit for the line
order_measurement_unit	Order measurement unit
quantity_in_order_unit	Quantity expressed in the order unit
public_custom_fields_list	Standard Versa custom fields on the line
supplier_part_number	Supplier part number on purchase order lines when an approved supplier record exists
supplier_comment	Supplier comment on the line
suppliers	Suppliers related to the line
related_invoices	Invoices related to the line
lot_numbers	Lot numbers on the line
lot_numbers_with_qty	Lot numbers with quantities
bin_location	Bin location for the line
is_kit_item / is_kit_item? / is_kit?	Whether the line is a kit item
child_item_seq_id	Child line sequence id for kit structures
parent	Parent line where applicable
associated_parent_order_items	Associated parent lines
work_orders	Related work orders
assigned_load	Load the line is currently assigned to in Load Management
freight_load	Load linked to the line for traceability after finalization/PO generation
load_order_item	Join record between the line and its assigned load

---

Standard custom fields on orders and lines

Versa custom fields created under the normal custom field setup can be accessed with custom_field_by_name or by looping public_custom_fields_list.

By field name

{{ order | custom_field_by_name: 'Driver' }}

{% for item in order.order_items %}
  {{ item | custom_field_by_name: 'DC' }}
{% endfor %}

Hide blank custom-field values

{% assign driver = order | custom_field_by_name: 'Driver' %}
{% if driver != blank %}
  Driver: {{ driver }}
{% endif %}

Loop public custom fields

{% for field in order.public_custom_fields_list %}
  {{ field.field_name }}: {{ field }}
{% endfor %}

See also: custom_field.

---

Load Management fields

When the Load Management feature is enabled, loads can be linked to orders and order lines. There are three different load-related objects depending on what you need.

Liquid field	Available on	What it represents
order.freight_load	Order header	The load linked to the order header for traceability, such as a dropship PO generated from a load
item.assigned_load	Order line	The load the sales order line is currently assigned to in Load Management
item.freight_load	Order line	The load linked directly on the line for traceability after finalization or PO generation
item.load_order_item	Order line	The join record between the line and its assigned load

Important: On the order header, use order.freight_load. The old name assigned_load is not available on the order object. Use item.assigned_load on order lines instead.

Built-in load fields

These are stored directly on the load and are not in additional_attributes:

{% if order.freight_load %}
  Load ID: {{ order.freight_load.display_load_id }}
  Manufacturer: {{ order.freight_load.manufacturer }}
  Distribution center: {{ order.freight_load.distribution_center }}
  Appointment info: {{ order.freight_load.appointment_information }}
  Bill of lading #: {{ order.freight_load.bill_of_lading_number }}
  Shipment status: {{ order.freight_load.shipment_status }}
{% endif %}

From an order line:

{% if item.assigned_load %}
  Assigned load: {{ item.assigned_load.display_load_id }}
{% endif %}

Other useful load-related collections

Field	Description
display_load_id	User-facing load id such as WMT-100
sequence_number	Numeric sequence portion of the load id
finalized?	Whether the load is finalized
assigned_order_items	Sales order lines currently assigned to the load
orders	Purchase orders generated from the load
purchase_order_items	PO lines generated from the load
shipment_batches	Shipment batches generated from the load

---

Accessing user-defined Load custom fields via additional_attributes

Load Management also supports user-defined load fields configured under:

Setup → Company → Loads → Field definitions

These are not standard Versa CustomField records and cannot be read with custom_field_by_name. They are stored on the load in additional_attributes, keyed by the field’s field key.

How to find the field key

1. Go to Setup → Company → Loads.
2. Open Field definitions.
3. Use the value in the Field key column, not the display label.

Example:

• Label: Dock Door
• Field key: dock_door
• Liquid: {{ load.additional_attributes.dock_door }}

From the order header

{% if order.freight_load %}
  Dock door: {{ order.freight_load.additional_attributes.dock_door }}
  Trailer #: {{ order.freight_load.additional_attributes.trailer_number }}
{% endif %}

From an order line

{% if item.assigned_load %}
  Gate code: {{ item.assigned_load.additional_attributes.gate_code }}
{% endif %}

Assign the attributes object first

{% if order.freight_load %}
  {% assign load_attrs = order.freight_load.additional_attributes %}

  {% if load_attrs.dock_door != blank %}
    Dock door: {{ load_attrs.dock_door }}
  {% endif %}

  {% if load_attrs.seal_number != blank %}
    Seal #: {{ load_attrs.seal_number }}
  {% endif %}
{% endif %}

What does not work for Load custom fields

Do not use	Why
{{ order.freight_load | custom_field_by_name: 'Dock Door' }}	custom_field_by_name is only for standard Versa custom fields
The field label from setup	Liquid uses the field key, not the label
order.assigned_load	That field does not exist on the order object

---

Common examples

Order header with customer and ship-to

Order #: {{ order.order_number }}
Date: {{ order.order_date | format_date }}
Customer: {{ order.customer_bill_to.party.company_name }}
Ship to: {{ order.ship_to_party.address_string }}
PO #: {{ order.external_order_reference_number }}

Line table

<table>
  <tr>
    <th>Line</th>
    <th>Item</th>
    <th>Qty</th>
    <th>Price</th>
    <th>Total</th>
  </tr>
  {% for item in order.order_items %}
    <tr>
      <td>{{ item.order_item_seq_id }}</td>
      <td>{{ item.description }}</td>
      <td>{{ item.quantity }}</td>
      <td>{{ item.per_unit_cost }}</td>
      <td>{{ item.line_item_value }}</td>
    </tr>
  {% endfor %}
</table>

Show load information on a sales order PDF

{% if order.freight_load %}
  {% assign load = order.freight_load %}
  {% assign attrs = load.additional_attributes %}

  <h3>Load {{ load.display_load_id }}</h3>
  <p>Manufacturer: {{ load.manufacturer }}</p>
  <p>DC: {{ load.distribution_center }}</p>

  {% if attrs.dock_door != blank %}
    <p>Dock door: {{ attrs.dock_door }}</p>
  {% endif %}
{% endif %}

---

Quick reference

You need…	Use…
Order number / date / total	order.order_number, order.order_date, order.total
Customer on a sales order	order.customer_bill_to
Supplier on a purchase order	order.supplier
Ship-to address	order.ship_to_party.address_string
Loop lines	{% for item in order.order_items %}
Standard custom field on order	{{ order | custom_field_by_name: 'Field Name' }}
Standard custom field on line	{{ item | custom_field_by_name: 'Field Name' }}
Load on order header	order.freight_load
Load currently assigned to a line	item.assigned_load
User-defined load custom field	order.freight_load.additional_attributes.<field_key> or item.assigned_load.additional_attributes.<field_key>
Supplier part number on PO line	item.supplier_part_number
Dimension tags	order.tags
Delivery route	order.route.name

---

Tips

• The root object is always order.
• Use order.freight_load on the header — not order.assigned_load.
• Use item.assigned_load on lines for the load the line is currently assigned to.
• Standard Versa custom fields use custom_field_by_name.
• Load Management custom fields use additional_attributes.<field_key>.
• Look up load field keys in Setup → Company → Loads → Field definitions.
• Guard optional values with {% if value != blank %} before printing rows.
• Test sales orders, purchase orders, and load-linked orders separately — available fields differ by order type and workflow state.