Skip to main content

ZPL how-to

Change a barcode to a QR code in ZPL

Changing a barcode into a QR code in ZPL is a one-line change, with two things to get right: the QA, at the start of the field data, and the ^BY left over from the barcode.

The barcode

A plant label with its number as a Code 128 barcode:

zpl
^XA
^CF0,40
^FO40,40^FDCelosia Argentea^FS
^FO40,100^BY4,2.0,65^BCN,100,Y,N^FD0933860^FS
^XZ

The same label with a QR code

zpl
^XA
^CF0,40
^FO40,40^FDCelosia Argentea^FS
^BY2,2,0^FO40,100^BQN,2,5^FDQA,0933860^FS
^FO190,140^FD0933860^FS
^XZ
  • ^BQN,2,5 takes the place of ^BCN,100,Y,N: a QR code, normal orientation, model 2, at magnification 5. The magnification sets its size, as the guide on QR code size explains.
  • QA, at the start of the field data is not printed. Q is the error correction level and A picks the data mode automatically. The number follows the comma.
  • ^BY4,2.0,65 becomes ^BY2,2,0. Its module width and ratio do nothing to a QR code, but its bar height moves the code down, as the next section shows. Deleting it is not enough: ^BY stays set until the next one, from earlier on the label or from an earlier label.
  • A QR code prints no text, so the number is its own field, to the right of the code.

Swap only the command, and the scan is wrong

Changing just the barcode command, and keeping everything else on the line, prints this:

zpl
^XA
^CF0,40
^FO40,40^FDCelosia Argentea^FS
^FO40,100^BY4,2.0,65^BQN,2,5^FD0933860^FS
^XZ
  • Without QA,, the start of the data is read as settings and dropped: in Labelary, two characters of a number and three of text. The code prints, with no error, and scans as 33860. A link fares the same: https://zeepler.com/r/A1 scanned as ps://zeepler.com/r/A1.
  • The QR code is drawn lower than ^FO by the bar height of the last ^BY. With the leftover ^BY4,2.0,65, its top edge is at 165, not 100. The fixed label's ^BY2,2,0 puts it at 101: Labelary draws a height of 0 as 1 dot. A printer that has had no ^BY since it was switched on uses 10.

The same label 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.

json
1{
2 "config": {
3 "size": "4x2"
4 },
5 "data": {
6 "name": "Celosia Argentea",
7 "number": "0933860"
8 },
9 "templates": [
10 {
11 "type": "Text",
12 "dataPath": "name",
13 "coords": [40, 40],
14 "font": "0,40"
15 },
16 {
17 "type": "QRCode",
18 "dataPath": "number",
19 "coords": [40, 100],
20 "magnification": 5
21 },
22 {
23 "type": "Text",
24 "dataPath": "number",
25 "coords": [190, 140],
26 "font": "0,40"
27 }
28 ]
29}

And the ZPL that comes back, ready to send to the printer:

zpl
^XA^MCY^XZ
    ^XA
    ^SZ2
    ^MMT
    ^MNY
    ^LL406
    ^PW812
    ^LH0,0
^CF0,40^FO40,40^FDCelosia Argentea^FS
^BY2,2,0^FO40,100^BQN,2,5^FDQA,0933860^FS
^CF0,40^FO190,140^FD0933860^FS
^XZ

In a zeepler request, change the element's type from BarCode to QRCode and add a magnification from 1 to 10. zeepler adds the QA, for you, and sets ^BY2,2,0 before every QR code, as the fixed label does, so a barcode earlier on the label never moves it: the code starts 1 dot below its coords.

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 200 with the ZPL as plain text. A request the API cannot turn into a label answers 400 with 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

  • Scan the QR code with your own scanners, and check it reads the whole value, first characters too.
  • Text does not wrap. A value longer than the space you left runs off the edge of the label, so set maxLength on 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

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.