JavaScript quickstart

This page shows how to convert labels from Node.js with the LabelZoom JavaScript SDK.

Before you begin

Install Node.js 20 or later.
Optional: Get an API key. Without one, output has a watermark. See Authentication.

Install the SDK

Install the @labelzoom/sdk package from npm:

npm install @labelzoom/sdk

Convert ZPL to PDF

Save the following program as convert.mjs:

import { writeFile } from 'node:fs/promises';
import { LabelZoomClient } from '@labelzoom/sdk';

const client = new LabelZoomClient();   // reads LABELZOOM_API_KEY

const result = await client.convert()
  .fromZpl('^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ')
  .toPdf()
  .withLabelSize(4, 6)                  // inches
  .withDpi(203)
  .execute();

await writeFile('label.pdf', result.bytes);

The SDK reads your API key from the LABELZOOM_API_KEY environment variable. To pass a key explicitly, use new LabelZoomClient({ apiKey: 'API_KEY' }). Create one client for your application and reuse it.

Run the program with node convert.mjs. It writes label.pdf.

Convert a PDF to ZPL

import { readFile } from 'node:fs/promises';

const result = await client.convert()
  .fromPdf(await readFile('shipping-label.pdf'))
  .toZpl()
  .withPdfPage(0)                       // 0-based; omit to convert every page
  .execute();

console.log(result.text);

Write PDF, image, and printer-language (EPL, IPL, TSPL, DPL, SBPL) output as bytes (result.bytes), not text; see Binary output.

Fill variable fields

const template = '^XA^FO50,50^A0N,30,30^FD{name}^FS^FO50,100^A0N,30,30^FD{sku}^FS^XZ';

const result = await client.convert()
  .fromZpl(template)
  .toZpl()
  .withData(                            // one label per record
    { name: 'ACME Corp', sku: '12345' },
    { name: 'Globex', sku: '67890' },
  )
  .execute();

console.log(result.text);

Each placeholder, such as {name}, takes its value from the matching key in each record; see Merge fields for the placeholder syntax.

Handle errors

import { LabelZoomError } from '@labelzoom/sdk';

try {
  await client.convert().fromZpl('^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ').toPdf().execute();
} catch (error) {
  if (!(error instanceof LabelZoomError)) throw error;
  console.error(`HTTP ${error.status}, request ID ${error.requestId}: ${error.message}`);
}

The SDK retries 429 and 5xx responses automatically before it throws. For status codes, see Errors.

Call the API without the SDK

To call the API with fetch instead of the SDK, send the label as the request body. This example runs on Node.js 18 or later, Bun, and Deno:

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

const zpl = "^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ";

// The API key is optional. Omit the Authorization header if it isn't set.
const headers = { "Content-Type": "text/plain" };
if (process.env.LABELZOOM_API_KEY) {
  headers.Authorization = `Bearer ${process.env.LABELZOOM_API_KEY}`;
}

const response = await fetch(
  "https://api.labelzoom.com/api/v2/convert/zpl/to/pdf?label.width=4&label.height=6&dpi=203",
  { method: "POST", headers, body: zpl },
);

if (!response.ok) {
  throw new Error(`Conversion failed: ${response.status} ${await response.text()}`);
}

await writeFile("label.pdf", Buffer.from(await response.arrayBuffer()));

To convert a PDF to ZPL, send the file’s bytes to /convert/pdf/to/zpl with Content-Type: application/pdf, and read await response.text().

To set options, send one params query parameter that holds JSON, or use dot notation such as label.width=4. Accept can be */*, the target’s media type, or a wildcard such as image/*. See Conversion parameters.