.docx Fields for Sales Documents

This article lists every merge field you can use in a Word template with the Sales category. It covers sale orders, quotes and invoices, and it shows which fields must sit inside a repeating block.

Use it as a lookup while you build your template. For the Word steps, see Build a .docx template in Word.

What a Sales template prints

One Sales template serves several documents. The same field names work for all of them.

You pick the template in the Print Document dialog, or in the Email document dialog under “Template to use to generate the Pdf Attachment:”. If no Sales template exists, the Print Document dialog offers Default Template and the Email document dialog shows Default Branding Theme. Both use the built-in design, not a .docx file.

Things to know before you build

The template cannot tell an order from an invoice, so these points shape how you design it.

• There is no field for the invoice number, invoice date, order status or document type. Number is always the order number.
• To show “QUOTE” or “INVOICE” in a heading, make one template per document type and pick the right one when you print.
• An invoice PDF is named Order_ followed by the order number, for example when you email it.
• On an invoice, SubTotal, TotalTax, Total, TotalDiscount and TotalUnitsCount cover that invoice’s lines. PaidAmount and TotalRefund cover the whole order.

How the field kinds work

Fields come in a few kinds. The kind decides how you write the name in Word.

Field names are not case-sensitive, so Subtotal and SubTotal both fill. A misspelled field, or one not on this page, prints nothing and gives no warning. The same happens to a dotted field whose parent is missing, such as ShippingAddress.City on an order with no shipping address. Check the spelling against these tables.

Put a block’s start and end markers around the table row you want repeated. Name the end marker exactly like the start marker. If RangeStart:OrderItems ends with RangeEnd:Items, the print fails.

Where you place the markers decides how the block repeats.

• In the first and last cell of one table row, the row repeats and the header row stays once.
• In separate paragraphs, everything between them repeats for each item.
• In the same paragraph, the items run on together in one paragraph.

A block with no items is removed. In a table, the header row above it stays, so an order with no charges still shows an empty charges table with only its header.

Numbers, dates and currency

Money fields are plain numbers. They carry no currency symbol, so add Currency next to them.

• Every amount prints in the order’s currency, not your company currency.
• Currency holds the symbol, such as $ or €. CurrencyName holds the code, such as USD.
• Several currencies share the $ symbol, so use CurrencyName when the difference matters.
• Dates include a time. They are shifted to the time zone of the person who prints.
• TotalDiscount, TotalRefund and CurrencyRate are not rounded by Qoblex.

Without a format switch, a number prints with all its decimals and no thousands separator, such as 1247.067. A date prints with its time, in a style that can vary, so always add a date format.

Add Word format switches to control this. These work:

The starter template uses \#0.00 for amounts and \@ "dddd, dd MMMM yyyy" for dates. True or False fields such as HasDiscount print those words.

Order fields

Use these fields anywhere outside the repeating blocks.

DueDate on an order with several invoices comes from one of them, so it may not match the invoice you are printing.

Company fields

These describe your own company.

The company address comes from one of your locations that cannot hold inventory, usually the first one, which is usually the billing or head-office location created when the account was set up.

There are no fields for a logo, email, website or tax number. Paste your logo into the Word file as an ordinary picture, and type the rest as fixed text.

Customer and contact fields

Customer is the contact on the order. Supplier returns the same contact, so on a sales document either name gives the same result. Use Customer.

Each contact address field takes the same eight address parts listed in the next section.

Customer.PrimaryAddress.* and Customer.SecondaryAddress.* need at least one saved address on the contact. If a contact has none, the print can fail with “There was an error while generating the pdf document.” Add an address to the contact, or use the order’s own addresses instead.

Address fields

Two kinds of address exist, and they are easy to mix up.

• ShippingAddress.* and BillingAddress.* are the addresses written on this order.
• Customer.ShippingAddress.* and Customer.BillingAddress.* are the addresses saved on the customer record.

For a document to the customer, use the order’s own addresses. They stay as they were when the order was placed, even if the customer record changes later.

Every address group has the same parts.

Write the group first, then the part, for example ShippingAddress.City or Customer.BillingAddress.Country. If an order may have no shipping or billing address, print a sample of one to see how the address area looks.

Totals fields

Use these in the totals area of your template, outside the repeating blocks.

Show a discount line only when there is one

The starter template uses a Word IF field with HasDiscount to print a line such as “Includes a discount of” only when it applies. The text shows only when HasDiscount is True. On an invoice, a fixed-amount discount line also makes HasDiscount True. Test an order or invoice with fixed-amount discounts before you rely on it.

Line item fields

Line items are the products on the order. Put these fields between RangeStart:OrderItems and RangeEnd:OrderItems, inside the table row you want repeated. Lines follow their order on the sale.

On an order that includes tax in its prices, Price and Total include tax. On other orders they do not.

Check totals on invoices

Every invoice, whether it covers all of an order or part of it, uses the invoice’s quantity, price and discount on its lines. If you use fixed-amount discounts, or your orders were imported with tax amounts, print a test invoice and compare the totals with your invoice in Qoblex.

Fields outside the block

Keep Number, Company.*, Customer.* and the totals outside the OrderItems block. Inside a block only that line’s fields fill, so any other field prints blank.

Additional charge fields

Additional charges, such as shipping and freight, are added on the order with Add Additional Charges. Print them with their own block: RangeStart:CustomItems and RangeEnd:CustomItems.

Charges have no Discount, SKU, Notes or Image field. Give the charges their own table rows so the whole block disappears when the order has none.

Custom field values on lines

You can print product variant custom fields on each line. Write CustomField: followed by the field’s key, for example CustomField:material_type, inside the OrderItems block.

Find the key

Open Branding and Customization and go to the Products section. The Custom Field Definitions table has a Key column. Copy the key exactly, including lower-case letters and underscores.

• A line whose product has no value for that key prints blank.
• Outside the OrderItems block the field prints blank.
• Custom fields on sale orders themselves cannot be printed.
• The value prints as the text stored in Qoblex. Dates and numbers are not reformatted.

Picture and HTML fields

Two prefixes change how a value is inserted.

The field Image on its own gives a web address as text, so always write it with the Picture: prefix. Check how a line with a picture, and one without, look in your test print, including the picture size.

Put an Html: field alone on its own line. Inside a sentence, the formatted paragraphs break out onto their own lines and split the text around them. With no notes, an Html: field prints nothing and its line disappears.

Older templates and fields that no longer fill

An old invoice template may use names from an earlier version of the field list. Those names no longer match any data, so they do not fill. This table shows what to use instead.

Inside the charges block, the charge name field is ItemName. These fields still fill: Company.Name, RangeStart:OrderItems, Quantity, ProductName, Price, Discount and RangeEnd:OrderItems.

If your template came from the starter download, you do not need this table. To rebuild an old template, see Build a .docx template in Word.

Before you rely on a field

Print a sample order after each change. Use an order that has several lines, an additional charge, a discount and notes, and then one that has none of them.

For the upload and test steps, see Upload and test a .docx template. If a PDF looks wrong, see Troubleshooting .docx templates.