Skip to main content
POST
/
api
/
templates
Create a template
curl --request POST \
  --url https://clarus-api.com/api/templates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Clarus-Subdomain: <api-key>' \
  --data '
{
  "data": {
    "type": "templates",
    "attributes": {
      "template_type_id": 1,
      "name": "Custom Dispatch Note",
      "default": false,
      "orientation": "Portrait",
      "page_height": 297,
      "page_width": 210,
      "top": 10,
      "bottom": 10,
      "left": 10,
      "right": 10,
      "header_height": 20,
      "header_spacing": 5,
      "footer_height": 15,
      "footer_spacing": 5
    }
  }
}
'
{
  "data": {
    "id": 123,
    "type": "templates",
    "attributes": {
      "template_type_id": 1,
      "name": "Custom Dispatch Note",
      "default": false,
      "orientation": "Portrait",
      "page_height": 297,
      "page_width": 210,
      "top": 10,
      "bottom": 10,
      "left": 10,
      "right": 10,
      "header_height": 20,
      "header_spacing": 5,
      "footer_height": 15,
      "footer_spacing": 5
    }
  }
}

​
Request Structure

{
  "data": {
    "type": "templates",
    "attributes": {
      "template_type_id": 1,
      "name": "Custom Dispatch Note",
      "default": false,
      "print_params": {
        "orientation": "Portrait",
        "page_height": 297,
        "page_width": 210,
        "top": 10,
        "bottom": 10,
        "left": 10,
        "right": 10,
        "header_height": 20,
        "header_spacing": 5,
        "footer_height": 15,
        "footer_spacing": 5
      }
    }
  }
}

​
Required Fields

FieldTypeDescription
template_type_idintegerID of the template type (see Template Type Discovery below)

​
Optional Fields

FieldTypeDescription
namestringDisplay name for the template
defaultbooleanWhether this is the default template for its type
template_header_idintegerID of a template to use as header
template_footer_idintegerID of a template to use as footer
print_paramsobjectPrint layout parameters (see below)
All dimensions are in millimeters (mm).
ParameterTypeDescription
orientationstringPortrait or Landscape
page_heightnumberPage height (e.g., 297 for A4)
page_widthnumberPage width (e.g., 210 for A4)
topnumberTop margin
bottomnumberBottom margin
leftnumberLeft margin
rightnumberRight margin
header_heightnumberHeight of the header area
header_spacingnumberSpacing between header and body
footer_heightnumberHeight of the footer area
footer_spacingnumberSpacing between body and footer

​
Template Type Discovery

Default template type codes (IDs vary per tenant but codes are consistent):
CodeDescription
dispatch_noteDispatch note for outbound shipments
picking_notePicking instructions for warehouse staff
commercial_invoiceCommercial invoice for international shipments
invoiceBilling invoice
put_away_notePut-away instructions for received goods
pre_receiptPre-receipt document for expected deliveries
pre_pick_labelLabel printed before picking
storage_unit_labelsLabels for storage units (pallets, cages, etc.)
pick_storage_unit_labelLabel for storage units created during picking
Actual template type IDs can be queried via GraphQL to find the ID for a given code.

​
Template Types and Liquid Variables

Each template type has access to different variables in Liquid templates. Top-level variables and their key nested properties:

​
dispatch_note

  • record - the goods out record (reference, created_at, status)
  • lines - goods out lines (product.code, product.description, quantity)
  • carrier - carrier details (name)
  • address - delivery address (address_1 through address_5, postcode, country_code)
  • account - stock account (name, code, address.*)
  • warehouse - warehouse (code, address.*)
  • customer - end customer (name, code)
  • subdomain - tenant info (currency.code, tax_rate.component_rate)
  • sales_order - linked sales order (reference)
  • total_weight - total weight of the shipment
  • products - product list with details

​
picking_note

  • goods_out_pick_list - pick list record (reference)
  • tasks - pick tasks (location, product, quantity)
  • carrier - carrier details
  • address - delivery address
  • account - stock account
  • warehouse - warehouse details
  • customer - end customer
  • subdomain - tenant info

​
commercial_invoice

  • shipment - shipment record (created_at)
  • packages - packages with dimensions.weight, stocks[].product.code/description/commodity_code/country_of_manufacture, stocks[].quantity, stocks[].dimensions.value/weight
  • account - stock account (name, address.*, gb_eori_number)
  • warehouse - warehouse (address.country_code)
  • subdomain - tenant info (currency.code, tax_rate.component_rate)
  • goods_out - outbound order (address.*)

​
invoice

  • record - invoice record
  • account - stock account
  • company - company details
  • lines - invoice lines

​
put_away_note

  • goods_in_receipt - receipt record
  • goods_in_receipt_lines - receipt lines
  • warehouse - warehouse details
  • account - stock account
  • supplier - supplier details
  • carrier - carrier details
  • subdomain - tenant info
  • tasks - put-away tasks

​
pre_receipt

  • goods_in_receipt - receipt record
  • account - stock account
  • warehouse - warehouse details
  • carrier - carrier details
  • supplier - supplier details
  • inbound_good_kind - type of inbound good
  • location - receiving location
  • lines - receipt lines

​
pre_pick_label

  • goods_out_pick_list - pick list record
  • goods_out - outbound order
  • product - product details

​
storage_unit_labels

  • stocks_lines[] - stock line records with: reference, product.code, product.description, goods_in_receipt, batch, account, location, confirmed_quantity, custom fields (boolean1-5, datetime1-5, integer1-5, string1-5)

​
pick_storage_unit_label

  • record - storage unit record
  • subdomain - tenant info (company details)

​
Liquid Template Syntax

Templates use Liquid syntax: 
<h1>Dispatch Note: {{ record.reference }}</h1>
<p>Date: {{ record.created_at | date: "%d/%m/%Y" }}</p>

{% for line in lines %}
  <tr>
    <td>{{ line.product.code }}</td>
    <td>{{ line.quantity | times: 1 }}</td>
    <td>{{ line.price | plus: 0 }}</td>
  </tr>
{% endfor %}

{% if carrier %}
  <p>Carrier: {{ carrier.name }}</p>
{% endif %}

​
Workflow

  1. Create template - POST /templates with template_type_id and print parameters
  2. Upload Liquid HTML - POST /templates//attachment with your .html.liquid file
  3. Test print - PATCH /templates//test to generate a test PDF
  4. Download test - Use Documents endpoints (POST /documents//download) to retrieve the generated PDF
  5. Set as default - Optionally PATCH /templates/ with default: true

Authorizations

​
Authorization
string
header
required

OAuth 2.0 authentication. Use the client credentials or authorization code flow to obtain an access token.

​
X-Clarus-Subdomain
string
header
required

The subdomain/tenant name identifying which tenant's data to access. Required for all API requests.

Body

application/json
​
data
object
required

Response

Template created successfully

​
data
object