Templates

Templates allow you to create dynamic PDF content using HTML and CSS.

In addition, using the Liquid templating language, you can easily render HTML dynamically based on variables you pass in via the API.

For example, if you produce invoice PDFs, you’ll need to pass through the invoice number, date, line items, prices, and addresses. Here’s what your API request might look like.


{
  "parts": [
    {
      "type": "template",
      // The slug is the unique, immutable identifier for your template
      // You can specify a version with the "@v1", "@v2" etc or point to "@latest"
      "slug": "hello-world@latest", 
      // Optionally include a "variables" object with the data you want to pass in
      "variables": {
        "invoiceNumber": "INV-123",
        "invoiceDate": "2024-03-07",
        "lineItems": [
          {
            "description": "Dog biscuits",
            "price": 10
          },
          {
            "description": "Squeaky toy",
            "price": 20
          }
        ]
      }
    }
  ]
}

In the template editor, you can write Liquid in your HTML to specify how these variables should be used.


<html>
  <head>
    <title>Invoice {{ variables.invoiceNumber }}</title>
  </head>
  <body>
    <h1>Invoice {{ variables.invoiceNumber }}</h1>
    <p>Date: {{ variables.invoiceDate }}</p>
    <table>
      <thead>
        <tr>
          <th>Description</th>
          <th>Price</th>
        </tr>
      </thead>
      <tbody>
        {% for lineItem in variables.lineItems %}
          <tr>
            <td>{{ lineItem.description }}</td>
            <td>{{ lineItem.price }}</td>
          </tr>
        {% endfor %}
      </tbody>
    </table>
  </body>
</html>

Liquid

Liquid is a simple, expressive language that allows you to output dynamic content in your templates. You can use Liquid to output variables, perform logic, and iterate over lists. To learn more about Liquid, check out the official documentation.

Template files

You can create text-based files like CSS and JavaScript to use in your templates. These files can be referenced in the usual ways, from your index.liquid by using a relative path.


<link rel="stylesheet" href="styles.css" />

Learn more about Stylesheets.

Template Assets

You can also upload static assets like images and fonts to use in your templates. These assets can be referenced in your HTML and CSS in the same way as template files.


<img src="logo.svg" alt="Company logo" />

Learn more about Images and Fonts.

Publishing

When you’re ready to use your template in production, you can publish it. This will create a versioned, immutable snapshot of your template that you can reference in your API requests.

To refer to a specific published version of your template, you can use the @v1, @v2, etc. syntax.


{
  "parts": [
    {
      "type": "template",
      "slug": "hello-world@v1"
    }
  ]
}

Alternatively, you can use @latest to always refer to the latest published version.


{
  "parts": [
    {
      "type": "template",
      "slug": "hello-world@latest"
    }
  ]
}