Connector template variables

Overview

Connector templates and template variables let you build custom API requests for connectors. Use them to dynamically populate payloads in the format required by a vendor’s endpoint, such as JSON or XML.

Templates define the structure of your API request and template variables provide the dynamic values.

For more information, see About connector templates.

How it works

Template variables are attribute mappings that provide the dynamic data for your templates.

For example, to include a dynamic order ID value in a template, map the attribute order_id to a template variable named orderID. Then, in the template, reference {{orderID}} where the order ID value should appear.

To add template variables, go to the connector action, click the Templates tab, and map attributes to variable names.

Data types

To use connector templates effectively, it’s important to understand the structure of the data used to render a template.

This section describes how to use template variables of different data types in templates, including how to reference values directly, use helper methods like .toJson, and how to iterate over multiple values.

These examples are based on the following template variable mappings:

Badge

A variable mapped to a badge attribute has the value true if it’s assigned or an empty value if it’s not assigned. A badge variable never has the value false, so to avoid blank values, use a section and inverted section to force a value of true or false.

Template variable values:

unbadgedBadge =
didSearchBadge = true

Template:

{
    "badge1": "{{unbadgedBadge}}",
    "badge2": {{didSearchBadge}},
    "badge1SectionInvert": {{#unbadgedBadge}}true{{/unbadgedBadge}}{{^unbadgedBadge}}false{{/unbadgedBadge}},
    "badge2SectionInvert": {{#didSearchBadge}}true{{/didSearchBadge}}{{^didSearchBadge}}false{{/didSearchBadge}}
}

Rendered template:

{
    "badge1": "",
    "badge2": true,
    "badge1SectionInvert": false,
    "badge2SectionInvert": true
}

Boolean

A variable mapped to a boolean is either true, false, or unassigned. Render the value directly or use it in section or inverted section logic. Boolean values are not quoted.

Template variable values:

returningVisitorBoolean = false

Template:

{
    "boolean": {{returningVisitorBoolean}},
    "booleanSectionTrue": {{#returningVisitorBoolean}}true{{/returningVisitorBoolean}},
    "booleanSectionInvert": {{^returningVisitorBoolean}}false{{/returningVisitorBoolean}}
}

Rendered template:

{
  "boolean": false, 
  "booleanSectionTrue": , 
  "booleanSectionInvert": false
}

Keep in mind that the boolean value might not be set. To handle this in a template, use section and inverted section logic to force a value to be rendered.

Template logic:

{
    "boolean": {{#returningVisitorBoolean}}true{{/returningVisitorBoolean}}{{^returningVisitorBoolean}}false{{/returningVisitorBoolean}}
}

Date

A variable mapped to a date attribute is represented as a timestamp (numbers) in the template data and rendered as ISO 8601 strings in the output.

Helper functions: formatDate, toTimestamp, toTimestampMs, unixTimestamp, unixTimestampMs.

Template variable values:

firstVisitDate = 1749081326718

Template:

{
    "date": "{{firstVisitDate}}"
}

Rendered template:

{
    "date": "2025-06-04T23:55:26.718Z"
}

Number

A variable mapped to a number attribute can be rendered directly or converted to an integer using .toInteger.

Template variable values:

lifetimeVisitCountNumber = 1.0

Template:

{
    "number": {{lifetimeVisitCountNumber}},
    "numberToInteger": {{lifetimeVisitCountNumber.toInteger}}
}

Rendered template:

{
    "number": 1.0,
    "numberToInteger": 1
}

String

A variable mapped to a string attribute can be referenced directly. If you are building a JSON template, use .toJson to ensure an escaped string that can be quoted.

Helper functions: hash, md5, sha1, sha256, substring.

Template variable values:

activeBrowserTypeString = "Chrome"

Template:

{
    "string": "{{activeBrowserTypeString.toJson}}"
}

Rendered template:

{
    "string": "Chrome"
}

Set of Strings

A variable mapped to a set of strings attribute is similar to an array but may not preserve order. To render a set of strings variable as an array, use .toJson. For more advanced cases, use an iteration to apply a custom format for each entry.

Helper functions: sum.

Template variable values:

activeBrowserTypesSetOfStrings = ["Chrome", "Safari"]

Template:

{
    "setOfStrings": {{activeBrowserTypesSetOfStrings}},
    "setOfStringsToJson": {{activeBrowserTypesSetOfStrings.toJson}},
    "setOfStringsIter": [
    {{#activeBrowserTypesSetOfStrings}}
        "-- {{.}} --"{{#iter.hasNext}},{{/iter.hasNext}}
    {{/activeBrowserTypesSetOfStrings}}
    ]
}

Referencing a set of strings variable directly, without .toJson or iterating, renders unquoted values.

Rendered template:

{
    "setOfStrings": [Chrome,Safari], 
    "setOfStringsToJson": ["Chrome", "Safari"],
    "setOfStringsIter": [
        "-- Chrome --",
        "-- Safari --"
    ]
}

Arrays

A variable mapped to an array attribute should be referenced with .toJson. For more advanced cases, use an iteration to apply a custom format for each entry.

Helper functions: sum.

Referencing an array variable directly renders unquoted values.

Template variable values:

browsersArray = ["Chrome", "Safari"]

Template:

{
    "array": {{browsersArray}},
    "arrayToJson": {{browsersArray.toJson}},
    "arrayIter": [
    {{#browsersArray}}
        "-- ({{iter.index}}) {{.}} --"{{#iter.hasNext}},{{/iter.hasNext}}
    {{/browsersArray}}
    ],
}

Rendered template:

{
    "array": [Chrome,Safari], 
    "arrayToJson": ["Chrome", "Safari"], 
    "arrayIter": [
        "-- (1) Chrome --",
        "-- (2) Safari --"
    ] 
}

Tally

A variable mapped to a tally attribute is a map of keys to numeric values. Use .toJson to render the full tally with quoted keys. Use .entrySet to iterate the tally, then key and value to reference the key-value pairs.

Referencing a tally directly renders unquoted values.

Template variable values:

categoriesTally = { 
    "Shirts" : 1, 
    "Blazers" : 2,  
    "Electronics" : 4, 
    "Eyewear" : 1 
}

Template:

{
    "tally": {{categoriesTally}},
    "tallyToJson": {{categoriesTally.toJson}},
    "tallyIter": {
        {{#each categoriesTally.entrySet}}
        "{{key}}": "{{value.toInteger}}"{{#iter.hasNext}},{{/iter.hasNext}}
        {{/each}}
    }
}

Rendered template:

{
    "tally": {Shirts=1, Blazers=2, Electronics=4, Eyewear=1},
    "tallyToJson": {
        "Shirts":1,
        "Blazers":2,
        "Electronics":4,
        "Eyewear":1
    }, 
    "tallyIter": { 
        "Shirts": "1",  
        "Blazers": "2", 
        "Electronics": "4",
        "Eyewear": "1" 
  }
}