Adding barcodes and QR codes to templates

This guide shows how to add scannable barcodes or QR codes to your print templates so customers, staff, or systems can quickly access or identify document data, products, or contacts.

Before you start:

• You must have permission to edit print templates.
• Decide what data each barcode should encode: invoice number, product code, customer ID, prescription, or a URL.
• Ensure your template has the necessary variables available (e.g., {{invoice.number}}, {{product.barcode_value}}). Consult the variables reference if unsure.
• Have a barcode scanner or smartphone with a QR reader app to test your output.

Adding a barcode or QR code:

1. Open the template editor. Go to Settings → Print Templates Open in Usystems and select the template you want to edit.

2. Locate where you want the code. Find the section of HTML where you want the barcode or QR code to appear (e.g., footer, top right, below customer details).

3. Add the barcode helper. Insert one of the following Handlebars helpers into your HTML:

   For a barcode (linear, best for product codes or invoice numbers):

   {{barcode variable_name type="code128"}}
   

   Example:

   <img src="{{barcode invoice.number type='code128'}}" alt="Invoice barcode" />
   

   For a QR code (square, best for URLs or longer data):

   {{qrcode variable_name}}
   

   Example:

   <img src="{{qrcode invoice_url}}" alt="Invoice QR code" />
   

4. Ensure the variable contains data. The variable you use must be available in your document and contain the data you want encoded. For example:

   • {{barcode invoice.number}} encodes the invoice number.
   • {{qrcode customer.contact_url}} encodes a customer contact URL.
   • If the variable is empty on a document, the barcode/QR code will not render.

5. Test the output. Save your template and print or preview a test document. Scan the barcode or QR code with appropriate equipment to confirm it encodes the correct data.

Common barcode types:

Use the type= parameter to specify the barcode format:

QR code best practices:

• Use for URLs: Encode a link to an online invoice portal, customer portal, or payment page. Example: {{qrcode invoice_payment_url}}.
• Use for contact data: Encode customer or vendor information in vCard format. Example: {{qrcode contact.vcard_url}}.
• Use for long data: QR codes can hold more data than linear barcodes (up to ~4,000 characters), so they are ideal for complex information.

Sizing the barcode or QR code:

Wrap the barcode in a <div> or <img> tag and use CSS to control its size:

<div style="text-align: center; margin: 10px 0;">
  <img src="{{qrcode invoice.number}}" alt="Invoice QR" style="width: 100px; height: 100px;" />
</div>

Tips & common mistakes:

• Make sure the variable exists. If you use {{qrcode undefined_variable}}, the QR code will not render. Always reference variables that exist on your document type.
• Test before printing at scale. Verify that barcodes/QR codes scan correctly with actual hardware (scanners, smartphones) before rolling out the template to your whole organization.
• Position clearly. Place barcodes and QR codes in a prominent, easy-to-scan location (e.g., top right, footer) and ensure they are not obscured by other content.
• Don't rely on color alone. While you can add color to the barcode area, ensure adequate contrast for scanning. Black barcodes on white background are most reliable.