Using custom scripts in notification templates

What is template scripting?

Notification templates support a scripting language called Liquid (powered by Scriban). This lets you include shipment data that is not available as a standard merge tag — such as custom reference fields — and add simple logic like "only show this section if a value exists."

You do not need to be a developer to use this feature, but it does require you to type code directly into the template editor.

When should I use scripting?

Use scripting when:

• You need a reference field that has no standard merge tag (for example, a custom order reference stored under a specific reference type)
• You want to show or hide a section depending on whether a value is present
• You need to build a custom URL using shipment data

For standard fields like receiver name, order number, or tracking link — use the regular merge tags. Scripting is for edge cases.
 

Where to add scripts in the editor

Scripts must be added inside an existing content block — not as a separate standalone block. If you add a script block on its own, it will create a blank gap in your email.

There are two places you will typically add scripts:

1. Inside a text block — for outputting a value as part of your email text
2. Inside a button's link field — for building a dynamic URL

Example 1: Show a reference field in email text

This example shows how to display a custom reference value (reference type 7 — Receiver reference) inside your email.

1. Open your template. Go to Portal > Settings > Notifications > Templates and open the template you want to edit.
    
2. Click into the text block where you want the value to appear. The script must live in the same block as the text around it — not in a separate block.
    

3. Type the script at the start of the block. Paste the following at the very beginning of the text block, before any other content:

   {%- for rf in references -%}{%- if rf.type_id == 7 -%}{%- assign ref_val = rf.value -%}{%- endif -%}{%- endfor -%}

   
   Then on the next line, add your label and output the value:

   Receiver reference: {{ ref_val }}

    

4. Preview the template. Use the Preview button and enter a barcode from a shipment that has a receiver reference. Confirm that the value appears correctly.
    

   

    

What if the reference is empty for some shipments?

Add a fallback so nothing looks broken. This hides the line entirely if no value is found:

{%- for rf in references -%}{%- if rf.type_id == 7 -%}{%- assign ref_val = rf.value -%}{%- endif -%}{%- endfor -%}
{% if ref_val %}Receiver reference: {{ ref_val }}{% endif %}

Example 2: Show a section conditionally

Use this to show a block of text only when a specific condition is met — for example, only showing pickup instructions when a pickup code exists.

{% if pickup_code %}
Your pickup code is: {{ pickup_code }}
Please show this code when collecting your parcel.
{% endif %}

Example 3: Dynamic button URL

Instead of linking to a fixed URL, you can include shipment data in the link.

1. Add a button block to your template.
    

2. Open the button's link settings and enter your URL. For simple fields, type the URL directly in the link field:

   https://anywebsite.no/?s={{any_number}}

   
   
   For a reference value in the URL:

   {%- for rf in references -%}{%- if rf.type_id == 7 -%}{%- assign ref_val = rf.value -%}{%- endif -%}{%- endfor -%}https://yourwebsite.com/search?ref={{ ref_val }}

   Note: Keep everything on one line with no space between the script and the URL.

Common reference type IDs

References are identified by a type_id number. Replace 7 in the examples above, with the type ID for the field you need.

If you are not sure which type ID your field uses, check the shipment in the Shipment Data API or contact nShift support.