Template Variables

Variables allow you to create dynamic templates that can be customized for each PDF generation.

Variable Syntax

Use double curly braces to insert variables in your template:

<h1>Invoice for {{clientName}}</h1>
<p>Invoice Number: {{invoiceNumber}}</p>
<p>Amount Due: ${{amount}}</p>
<p>Date: {{date}}</p>

Defining Variables

In the template editor:

1. Open the Variables panel
2. Click "Add" to create a new variable
3. Set the following properties:
   • Name: The identifier (e.g., clientName)
   • Type: The data type (text, number, date, boolean)
   • Default Value: Optional fallback value
   • Description: Optional description for documentation
4. Click "Insert" to add the placeholder to your template

Supported Data Types

Text

String values for names, addresses, descriptions, etc.

<p>Customer: {{clientName}}</p>
<p>Address: {{address}}</p>

API Example:

{
  "variables": {
    "clientName": "John Doe",
    "address": "123 Main Street"
  }
}

Number

Numeric values for amounts, quantities, prices, etc.

<p>Quantity: {{quantity}}</p>
<p>Price: ${{price}}</p>
<p>Total: ${{total}}</p>

API Example:

{
  "variables": {
    "quantity": "5",
    "price": "99.99",
    "total": "499.95"
  }
}

Date

Date values in ISO format (YYYY-MM-DD).

<p>Invoice Date: {{invoiceDate}}</p>
<p>Due Date: {{dueDate}}</p>

API Example:

{
  "variables": {
    "invoiceDate": "2024-01-15",
    "dueDate": "2024-02-15"
  }
}

Boolean

True/false values for conditional content.

<p>Premium Member: {{isPremium}}</p>

API Example:

{
  "variables": {
    "isPremium": "true"
  }
}

Variable Requirements

Required vs Optional Variables

All variables defined in the template editor are required when making API requests. However, you can:

1. Set default values: Provide fallback values in the editor
2. Use empty strings: Pass "" for optional text fields
3. Handle missing data: Transform your data before sending

Variable Best Practices

1. Use Descriptive Names

✅ Good: clientName, invoiceNumber, totalAmount
❌ Bad: cn, num, x

2. Be Consistent with Naming

✅ Good: firstName, lastName, emailAddress (camelCase)
✅ Good: first_name, last_name, email_address (snake_case)
❌ Bad: firstName, last_name, EmailAddress (mixed)

3. Set Meaningful Default Values

Use defaults for preview and development:

• clientName: "John Doe"
• amount: "1,000.00"
• date: "2024-01-15"

4. Document Your Variables

Add descriptions to help team members understand each variable's purpose.

5. Validate Before Sending

function validateVariables(template, variables) {
  const required = ['clientName', 'amount', 'date'];

  for (const varName of required) {
    if (!variables[varName]) {
      throw new Error(`Missing required variable: ${varName}`);
    }
  }
}

Common Patterns

Formatting Currency

Format currency before sending:

const variables = {
  amount: new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD',
  }).format(1000),
};
// Result: "$1,000.00"

Formatting Dates

Format dates to human-readable strings:

const variables = {
  date: new Date().toLocaleDateString('en-US', {
    year: 'numeric',
    month: 'long',
    day: 'numeric',
  }),
};
// Result: "January 15, 2024"

Handling Lists

For lists of items, generate HTML before sending:

const items = [
  { name: 'Product A', price: 100 },
  { name: 'Product B', price: 200 },
];

const itemsHtml = items
  .map(item => `<li>${item.name}: $${item.price}</li>`)
  .join('');

const variables = {
  itemsList: `<ul>${itemsHtml}</ul>`,
};

Then in your template:

<div>{{itemsList}}</div>