n8n integration

The verified LabelZoom node converts and prints labels from an n8n workflow, on n8n Cloud or self-hosted n8n.

Before you begin

• An n8n 2.x instance. To install the node, you need the owner or admin role.
• Optional for converting: a LabelZoom API key. To print, you need a key with the print scope and a printer connected through the LabelZoom Print Agent.

Install

Installing the node turns it on for everyone on the instance. To install it, follow these steps:

1. On the canvas, open the nodes panel: click +, or press N.
2. Search for LabelZoom.
3. Under More from the community, select LabelZoom, and install it.

If verified community nodes are turned off on your instance, install the node by its package name instead:

1. Go to Settings > Community nodes, and click Install.
2. In npm Package Name, enter n8n-nodes-labelzoom.
3. Select I understand the risks of installing unverified code from a public source, and then click Install.

Add credentials

To add your API key, follow these steps:

1. In the LabelZoom node, open Credential to connect with, and select Create new credential.
2. In API Key, paste a key from the dashboard.
3. Click Save. n8n tests the key and shows Connection tested successfully.

Field	Description
API Key	Optional for Label operations, which run on the free tier without a key. Required for Printer operations, with the print scope, which includes convert.
Max Retries	How many times to retry a 429 or 5xx response, with exponential backoff. 0 fails fast. Other errors aren’t retried.
Base URL	Change it only if you were given a dedicated endpoint.

The credential test rejects an invalid key, but a conversion with an invalid key runs anonymously instead of failing; see Authentication troubleshooting.

Convert ZPL to PDF

To convert a label, follow these steps:

1. Add a LabelZoom node, and set Resource to Label and Operation to Convert.
2. Set Source Format to ZPL and Target Format to PDF.
3. Set Input Type. For Text, paste the ZPL in Label Content. For Binary File, set Input Binary Field to the field that holds the file.
4. Optional: Under Options, set Label Width (Inches), Label Height (Inches), and DPI. Leave the width and height unset to use the label’s own size.

The node outputs the PDF in the binary field data.

Convert a PDF to ZPL

To convert a PDF, such as a carrier label, follow these steps:

1. Add an HTTP Request node that downloads the PDF, and set its Response Format to File.
2. Add a LabelZoom node with Resource set to Label, Operation to Convert, Source Format to PDF, Target Format to ZPL, and Input Type to Binary File.
3. Optional: Under Options, set PDF Page Number to convert one page. Page numbers are 0-based. Leave it unset to convert every page.
4. Optional: Set PDF Conversion Mode. Image, the default, rasterizes each page and keeps its appearance. Native extracts the vector and text content.

The ZPL is in the binary field data and also in the text field of the JSON output.

Fill variable data

To fill a label’s merge fields, convert to ZPL or another printer language, and put the values in Options > Variable Data (JSON). Each array entry produces one label:

[{ "sku": "A-100", "qty": "12" }, { "sku": "A-101", "qty": "5" }]

To map the values from the incoming item, use an expression such as {{ JSON.stringify($json.rows) }}. See Variable data.

Print a label

To send a document to a printer, follow these steps:

1. Add a LabelZoom node, and set Resource to Printer and Operation to Print.

2. In Printer, choose a printer. The list shows each printer’s native format and status, such as Warehouse Zebra — ZPL (ready).

   

3. Set Source Format. Leave it on Auto-Detect, except for printer languages such as ZPL and EPL, which you must choose.

4. Set Input Type and the document, as in Convert ZPL to PDF.

5. Optional: Set Copies, from 1 to 9999. Copies needs n8n-nodes-labelzoom 1.2.0 or later; see Copies.

You don’t need to convert first: LabelZoom converts the document to the printer’s native format in transit. Transform Options, such as rotation, apply too.

The node returns when the job is accepted. dispatched and queued mean accepted, not printed: to wait for completed or failed, turn on Wait for Completion, or check later with Printer > Get Job. See Job statuses.

The Idempotency Key field defaults to {{ $execution.id }}-{{ $itemIndex }}, which makes a retried step safe. To make a rerun of the whole workflow safe, set it from a business value such as {{ $json.orderNumber }}, and give each deliberate reprint a new key; see Idempotency.

Print a template

To print a template designed in LabelZoom Studio, send only the values. Follow these steps:

1. Add a LabelZoom node, and set Resource to Printer and Operation to Print Template.

2. In Printer and Template, choose from the lists. The template list shows each template’s merge fields, such as Shipping Label — orderNumber, sku.

   

3. In Merge Data (JSON), map one object of values, keyed by field name:

   {{ JSON.stringify({ orderNumber: $json.number, sku: $json.line_items[0].sku }) }}

4. Leave Validate Merge Fields on. It rejects a job with a missing field, which would otherwise print as the text null.

5. Optional: Set Copies.

Send one object per item. The node runs once for each input item, and each item becomes its own job. See Templates.

To render a filled template without printing it, for a preview or an approval step, use Label > Convert Template.

Troubleshooting

Symptom	Fix
LabelZoom doesn’t appear in the nodes panel.	Verified community nodes are turned off. On n8n Cloud, the owner turns them on in the Admin Panel. Self-hosted instances use environment variables. Restart n8n if needed, or install by package name.
The output has a watermark.	The key is missing or invalid, or the account has no paid plan; see Authentication troubleshooting.
Only the first label converts, and later labels are a placeholder.	The free tier converts the first label only; see Free tier.
A label prints null.	A merge field is missing or misspelled. Turn on Validate Merge Fields and check the field names.
A Printer operation fails with 403.	The key lacks the print scope.
A print fails with 422 and agent_update_required.	Copies needs an up-to-date agent; see Update the agent.
A print fails with 422 and idempotency_key_reused.	The key was used for a different request. Use a new key for each reprint.

Production checklist

• Use a live key, and keep it in an n8n credential, never in a node parameter; see Authentication.
• A bad key converts anonymously. Check your first output for a watermark; see Authentication troubleshooting.
• Every workflow that uses a key shares its rate limit; see Rate limits.
• Retry only 429 and 5xx. Don’t retry 401 or 403; see Retry failed requests.
• Give each deliberate reprint a new idempotency key; see Idempotency.

What’s next

• Conversion parameters
• Cloud Print API
• Merge fields
• LabelZoom Print Agent
• Zapier integration
• Binary output, for calling the API from a Code node