ZPL how-to
Several labels in one ZPL job
Every ^XA … ^XZ block is one label, and a job can hold as many as you like. The catch is that settings from one label carry into the next.
Join the labels
Put one label after another and send them together. Two different labels in one job:
^XA
^CF0,50
^FO40,40^FDBin 117-1^FS
^BY2^FO40,120^BCN,80,N,N^FD117-1^FS
^XZ
^XA
^CF0,50
^FO40,40^FDBin 117-2^FS
^BY2^FO40,120^BCN,80,N,N^FD117-2^FS
^XZIn Labelary this printed two labels, each with its own text and barcode. There is no separator to add and nothing to put around them: the printer starts a new label at each ^XA.
What carries into the next label
Many settings do not reset between labels: one that a label sets stays in force for the next unless that label sets it again. Here the second label sets no font:
^XA
^CF0,80
^FO40,40^FDBin 117-1^FS
^XZ
^XA
^FO40,40^FDBin 117-2^FS
^XZIn Labelary its text printed 60 dots tall, in the first label's ^CF0,80, not in the printer's small default font. The same goes for:
^BY, the barcode module width and height, which also moves a QR code (Change a barcode to a QR code).^LHand^PW(Label size and origin).^CI28, the UTF-8 switch (Accented characters).^FWand^PO, field rotation and justification and whole-label rotation. Reset^FWwith^FWN,0: plain^FWNkeeps an earlier justification (Rotate text and barcodes).^PMand^LR, mirror image and reverse print. In Labelary, a label after^XA^PMY^XZprinted mirrored.
Have every label set what it relies on, as the two labels at the top of this page each set ^CF and ^BY. Then each prints the same on its own, first in the job, or after anything else.
A numbered run: ^SN and ^PQ
When the labels differ only by a number that goes up by one, the printer can count for you. ^SN takes the place of ^FD, and ^PQ sets how many labels to print:
^XA
^CF0,50
^FO40,40^SNBin 117-1,1,N^FS
^PQ4
^XZ- In Labelary this printed four labels, "Bin 117-1" to "Bin 117-4". The printer counts up the last number in the value, here the 1 after the dash.
^SNBin 117-1,1,N: start at Bin 117-1, add 1 for each label, no leading zeros. A negative step counts down.- Zebra's reference notes one surprise: if the printer runs out of labels or ribbon in the middle of a run, it prints the interrupted number again once it is reloaded, in case that label did not print in full.
- The count ends with the label:
^PQdoes not carry into the next one. In Labelary, this run followed by a plain label printed five labels, not eight.
Several labels with zeepler
Send this body to POST https://api.zeepler.com/v1/zeeplify with your API key in the x-api-key header. It is a working request, not an illustration: on every change, our tests run this same file through the API's code and compare the result with the ZPL below.
1{2 "config": {3 "size": "4x2"4 },5 "data": {6 "bin": "Bin 117-1",7 "code": "117-1"8 },9 "templates": [10 {11 "type": "Text",12 "dataPath": "bin",13 "coords": [40, 40],14 "font": "0,50"15 },16 {17 "type": "BarCode",18 "dataPath": "code",19 "coords": [40, 120]20 }21 ]22}And the ZPL that comes back, ready to send to the printer:
^XA^MCY^XZ
^XA
^SZ2
^MMT
^MNY
^LL406
^PW812
^LH0,0
^CF0,50^FO40,40^FDBin 117-1^FS
^BY2,2,59^FO40,120^BCN,,N,N,N,A^FD117-1^FS
^XZzeepler makes one label per request. To print several, make one request for each label, join the responses one after another, and send the result to the printer in one go. Each response starts with an ^XA^MCY^XZ block that prints nothing, so joined responses need nothing between them.
- Every response sets
^LH0,0,^PWand^LLitself, and sets^BYbefore every barcode and QR code, so none of those carry over from the label before. - The font does. A Text element without a
fonthas no^CFof its own, so it takes the font the previous label left. In Labelary, a zeepler label whose Text had nofontprinted 7 dots tall on its own and 60 dots tall after a label that used"0,80". Give the first Text element of every label afont, as this request does. - So do
^FW,^PO,^PMand^LR: field rotation and justification, whole-label rotation, mirror image and reverse print. zeepler leaves them as they are unless the request'sconfigsets"resetPrinter": true; then each label starts with^FWN,0^PON^PMN^LRN. In Labelary, this request printed at x 40 to 254, y 40 to 178 on its own, at x 592 to 771, y 151 to 361 after^XA^FWR^POI^XZ, and at x 556 to 771, y 39 to 178, mirrored, after^XA^PMY^LRY^XZ. WithresetPrinter, sent after all four, it printed as it did on its own. - zeepler has no serial numbers: send each number as its own request, as the data of one label.
Sending it
- Call the API from your own server or integration engine, not from a web page. An API key in a browser is a key anyone can copy.
- A successful call answers
200with the ZPL as plain text. A request the API cannot turn into a label answers400with every problem listed by field, and is not billed. - Send the ZPL to a Zebra or other ZPL printer at 203 dpi. At 300 dpi the same label prints at two-thirds of the size.
The API reference has every field and status code.
Before you go live
- Text does not wrap. A value longer than the space you left runs off the edge of the label, so set
maxLengthon any field whose length you do not control. - Coordinates are in dots from the top-left corner. Print one label, measure it, and adjust: there is no preview.
- Scan every barcode and QR code on a printed label before relying on it.
Related guides
- QR code size in ZPL: How ^BQ magnification sets the size of a QR code, and how to work out the size in dots.
- Printing ^, ~ and _ in ZPL: Why a caret or tilde in your data cuts the field short, and how ^FH prints them.
- Font size in ZPL: Setting text height with ^A and ^CF, converting points to dots, and why ^CF carries over.
- Send ZPL to a Zebra printer from C#: Send ZPL from .NET to a network printer on port 9100, or to a USB printer through the Windows spooler, without the driver redrawing it.
- Code 128 barcodes in ZPL: Set a Code 128 barcode's width and height with ^BY and ^BC, work out its width in dots, and pick subsets A, B and C.
- Accented characters in ZPL (^CI28): Print é, ç, ô and € with ^CI28, switch the printer back with ^CI0, and what to do on older firmware.
- Send ZPL to a Zebra printer from Python: Send ZPL from Python to a network printer on port 9100, or to a USB printer through the Windows spooler, without the driver redrawing it.
- Change a barcode to a QR code in ZPL: Swap ^BC for ^BQ, start the field data with QA, so the first characters scan, and reset the ^BY left over from the barcode.
- Send ZPL to a Zebra printer from Node.js: Send ZPL from Node.js to a network printer on port 9100 or to a USB printer through a Windows printer share, and print from a web page through your server.
- Label size and origin in ZPL (^PW, ^LL, ^LH): Set the label size in dots with ^PW and ^LL, move 0,0 with ^LH, and stop the last label's settings moving this one.
- Templates in ZPL: store a format with ^DF, fill it with ^XF: Store a label layout on the printer with ^DF and ^FN, fill it with ^XF, and what prints when a field or the format is missing.
- EAN-13 and Code 93 barcodes in ZPL: Print EAN-13 with ^BE and Code 93 with ^BA, and the data each one changes: a replaced check digit, and characters Code 93 cannot hold.
- Print copies of a ZPL label with ^PQ: Print several copies of one label with ^PQ, why ^PQ after ^XZ prints only one, and each serial number twice with ^SN.
- Center text in ZPL with ^FB: Center text of any length with ^FB, why centered text sits a little left, and text too long for the block.
- Center or right-align a barcode in ZPL: Right-align a barcode with the third value of ^FO, center one by working out its width, and why ^FB does not move it.
- Wrap text and new lines in ZPL: Wrap long text with ^FB, start a new line with \&, and stop ^FB writing over its last line or cutting text off.
- Rotate text and barcodes in ZPL: Turn text and barcodes with N, R, I and B, where ^FO and ^FT put a turned field, ^FW and ^POI, and why both stay set.
Help with an integration
Email info@zeepler.com. You will get a reply within 2 business days. The support policy covers response times and version changes.