Skip to content
LabelZoom Docs

Conversion parameters

Conversion parameters control how the API reads the input and writes the output. Pass them as one params query parameter that holds JSON (recommended), or in dot notation:

POST https://api.labelzoom.com/api/v2/convert/pdf/to/zpl?params={"dpi":300,"label":{"width":4}}
POST https://api.labelzoom.com/api/v2/convert/pdf/to/zpl?dpi=300&label.width=4

URL-encode the params value. If you send both forms, dot notation wins where they conflict.

Unknown keys are ignored, so a misspelled parameter has no effect. A value of the wrong type, or malformed JSON, returns 400. Enum values are case-insensitive.

Parameters

Section titled “Parameters”
Parameter Type Default Description
label.width Number (inches) None Output label width. Omit it to use the size the label code declares; see Label size.
label.height Number (inches) None Output label height.
dpi Integer 203 Printer density, in dots per inch (203 dpi is 8 dots/mm). Use the density of the target printer; see Printer density.
rotation Integer (degrees) 0 Rotates the output. Must be a multiple of 90.
scaling Number (percent) 100 Scales an image or PDF source. 50 halves the size.
colorMode BW, GRAYSCALE, or COLOR GRAYSCALE Image or PDF to ZPL: GRAYSCALE dithers to simulate gray, and BW is pure black and white. Image targets: BW returns a black-and-white image, and other values return color.
darkness Integer (0–100) 70 Black-and-white threshold. Raise it to darken thin lines and small text.
position.x, position.y Integer (dots) 0 Image or PDF to ZPL: the image’s offset on the label. A negative value crops the image.
labelIndex Integer (0-based) None Converts only this label, on every plan. The response’s X-Total-Count header gives the number of labels in the input. Out of range returns 404.
data JSON array None Merge field values, one label per entry. See Variable data.
dialect String None ZPL output dialect, such as moca. Paid plans only.
watermark Boolean false Adds a watermark.
pdf.conversionMode IMAGE or NATIVE IMAGE PDF source. IMAGE rasterizes each page and keeps its appearance. NATIVE extracts the text and vector content.
pdf.pageNumber Integer (0-based) None PDF source. Converts one page. Omit it for every page.
pdf.compression NONE or OBJECT_STREAMS NONE PDF target. NONE writes PDF 1.4 for older PDF tools. OBJECT_STREAMS writes a smaller PDF 1.6 file.
zpl.imageCompression Z64 or COMPRESSED_HEX Z64 ZPL target. Use COMPRESSED_HEX for older printer firmware.
zpl.commandsToIgnore Array of strings [] ZPL source. Commands to skip, such as ["^PQ"].

Label size

Section titled “Label size”

For each dimension, the API uses the first of these sources that sets it. Width and height are resolved separately.

  1. label.width or label.height in the request, in inches.
  2. The size that the label code declares.
  3. The extent of the label’s content.

A requested size wins even when the code declares a different one. Content past the edge of the label is clipped, as it is on a printer.

Source format Width Length
ZPL ^PW ^LL
EPL q Q on gap media. Q with a gap of 0 is continuous media and sets no length.
TSPL SIZE SIZE
DPL <STX>KcLW None (from the content)
SBPL <ESC>A1 <ESC>A1
IPL None (from the content) None (from the content)

For example, ZPL with ^PW812 and no ^LL gets its width from ^PW (4 in at 203 dpi) and its height from the content. Sending only label.height sets the height and leaves the width to the code.

# Use the size from the label code, or from the content
POST /api/v2/convert/zpl/to/pdf?dpi=203


# Render on 4 × 6 in stock, whatever the code declares
POST /api/v2/convert/zpl/to/pdf?label.width=4&label.height=6&dpi=203

Variable data

Section titled “Variable data”

data is a JSON array. Each entry fills the template’s merge fields and produces one label on a printer-language target (ZPL, EPL, IPL, TSPL, DPL, or SBPL).

Terminal window
curl -X POST "https://api.labelzoom.com/api/v2/convert/zpl/to/zpl" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: text/plain" \
  -H "Accept: */*" \
  --url-query 'params={"data":[{"sku":"A-100"},{"sku":"A-101"}]}' \
  --data-binary '^XA^FO50,50^A0N,40,40^FD~sku,20~^FS^XZ' \
  --output labels.zpl

--url-query (curl 7.87 and later) encodes the value into the query string and leaves the body alone. Don’t use --get --data-urlencode: --get moves the label body into the query string too, and the API returns 400. On older curl, percent-encode the JSON yourself.

Limits

Section titled “Limits”
Limit Behavior
ZPL ^PQ (print quantity) A value above 1000 is reduced to 1000.
Label size for image targets At most 15 × 15 in at 203 dpi. Larger returns 400.
rotation Not a multiple of 90 returns 400.

What’s next

Section titled “What’s next”