Convert ZPL to PDF in Node.js

To convert ZPL to PDF in Node.js, send the ZPL with fetch as the body of a POST to the OpenZPL render endpoint, with Accept: application/pdf, and stream the response to a file. Node 18 and later have fetch built in, so no package is needed.

Mis à jour le 2026-10-20 · Renders made with the OpenZPL engine

What you need

• Node.js 18 or later: fetch, AbortSignal.timeout and web streams are built in. The code below uses ES modules (.mjs).
• The label size in inches and the printer density (8dpmm for 203 dpi).

The minimal request

import { writeFile } from "node:fs/promises";

const zpl = "^XA^FO50,50^A0N,50,50^FDHello from Node^FS^XZ";
const res = await fetch("https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/", {
  method: "POST",
  headers: { Accept: "application/pdf" },
  body: zpl,
});
if (!res.ok) throw new Error(await res.text());
await writeFile("label.pdf", Buffer.from(await res.arrayBuffer()));

fetch doesn't throw on a 400 or a 429: check res.ok yourself, or you will write the error text into a file named .pdf.

A small module for production

Save this as label-api.mjs. It streams the PDF to disk instead of buffering it, aborts a request after 30 seconds, and on 429 or 503 waits the seconds the API puts in Retry-After before trying again.

import { createWriteStream } from "node:fs";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";
import { setTimeout as sleep } from "node:timers/promises";

const API = "https://api.openzpl.com/v1/printers";

export async function zplToPdf(zpl, path, { dpmm = 8, size = "4x6", apiKey, retries = 3 } = {}) {
  const headers = { Accept: "application/pdf" };
  if (apiKey) headers["X-API-Key"] = apiKey;
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(`${API}/${dpmm}dpmm/labels/${size}/`, {
      method: "POST",
      headers,
      body: zpl,
      signal: AbortSignal.timeout(30_000),
    });
    if ((res.status === 429 || res.status === 503) && attempt < retries) {
      await res.body?.cancel();
      await sleep(Number(res.headers.get("Retry-After") ?? 1) * 1000);
      continue;
    }
    if (!res.ok) throw new Error(`HTTP ${res.status}: ${(await res.text()).trim()}`);
    // Stream the PDF to disk instead of buffering it in memory.
    await pipeline(Readable.fromWeb(res.body), createWriteStream(path));
    return Number(res.headers.get("X-Total-Count"));
  }
}

The label in this guide's example, as the engine renders it:

^XA
^CI28
^FO30,30^A0N,40,40^FDCeramic mug, 350 ml^FS
^FO30,85^A0N,26,26^FDSKU MUG350WHT^FS
^FO30,125^A0N,26,26^FDBatch 26.10^FS
^FO30,190^A0N,50,50^FD$12.90^FS
^FO590,30^BQN,2,5^FDLA,https://openzpl.com/p/MUG350^FS
^XZ

Batch: one PDF per order

Run requests one after another rather than all at once with Promise.all: the free plan allows 3 requests per second per IP, and a burst only buys you 429 responses. The module above already waits when told to.

import { zplToPdf } from "./label-api.mjs";

const orders = [
  { id: "10482", name: "Alex Morgan" },
  { id: "10483", name: "Sam Lee" },
  { id: "10484", name: "Rosa Diaz" },
];

// One request per order, one after another: the free plan allows
// 3 requests per second, and zplToPdf waits when the API says so.
for (const o of orders) {
  const zpl = `^XA^CI28^FO40,40^A0N,50,50^FD${o.name}^FS^FO40,110^A0N,30,30^FDOrder ${o.id}^FS^XZ`;
  await zplToPdf(zpl, `order-${o.id}.pdf`, { size: "4x2" });
}

Against a server limited to one request per second, the three orders took about two seconds: two of the requests got a 429 and were retried after one second, and all three PDFs were written.

Variants

• In the browser: the same fetch works from a web page; the API sends CORS headers and exposes X-Total-Count and Retry-After. Turn the response into a link with URL.createObjectURL(await res.blob()).
• PNG preview: omit Accept and add the label index (.../4x6/0/).
• Your key: pass { apiKey: process.env.OPENZPL_KEY }; never ship a key in browser code.

Erreurs

Limites

• Endpoint: POST https://api.openzpl.com/v1/printers/8dpmm/labels/4x6/ with the ZPL as the request body. The density is 6dpmm, 8dpmm, 12dpmm or 24dpmm; the size is in inches, up to 15 per side.
• Accept: application/pdf without a label index returns every label, one per page. Add an index (.../4x6/0/) to get a single label.
• Free plan: no key, 3 requests per second and 5,000 labels per day per IP address. Every label counts, ^PQ copies and PDF pages included. See pricing.
• Per request: up to 50 labels and 1 MB of ZPL.