Everything you need to generate QR codes in ZPL: ^BQ syntax, parameters, error correction, sizing and copy-paste examples — free, no signup.
TL;DR
QR codes in ZPL are generated by the ^BQ command. Basic syntax: ^FOx,y ^BQ orientation,model,magnification ^FD <ECC><mode>,data ^FS. Always use model 2 (model 1 is legacy). The ^FD payload starts with two letters: the first is the error-correction level (H, Q, M, L) and the second is the input mode (A = automatic encoding, M = manual segments). HA, is the safe default for shipping/outdoor (H recovery + auto). Magnification (1-10) controls module size — start with 5 on a 4×6 inch label at 203 dpi. Add ^CI28 inside the format to enable UTF-8 in the payload.
Try our free ZPL tools right now
Free, runs in your browser — Instant results
A QR code in ZPL is a two-dimensional barcode generated by the ^BQ command — one of the most powerful symbologies supported by Zebra printers. A single QR code can store up to 4,296 alphanumeric characters or 7,089 numeric digits, supports Reed–Solomon error correction (so it stays readable when partially damaged or dirty), and works with any smartphone camera as well as industrial scanners. That makes it the universal choice for tracking URLs, vCard contact cards, GS1 application identifiers, WiFi credentials, transit tickets and any payload that exceeds the 20-character sweet spot for 1D barcodes.
In ZPL, the QR code lives inside an ^XA..^XZ format like any other field. You position it with ^FO or ^FT, declare it with ^BQ, and then in ^FD you prepend two characters before the comma and the actual data: the first character is the error-correction level (H, Q, M or L) and the second is the input mode (A for automatic encoding selection, M for manual segments). For most production use cases you write ^FDHA,data^FS — high recovery, automatic encoding. There is no separate ^BY width step because the QR module size is controlled directly by the magnification parameter — typical values are 4 to 8 on a 4×6 inch label at 203 dpi. The model parameter should always be 2 (model 1 is legacy and not recommended for new designs).
The minimal QR code declaration takes 3 parameters after ^BQ — orientation, model and magnification. The error-correction level and input mode go inside ^FD as a 2-character prefix followed by a comma (see Field Data Format below). The canonical structure is:
^XA
^CI28 ; UTF-8 for international data
^FO50,50 ; Position X=50, Y=50
^BQ orientation,model,magnification ; orientation N/R/I/B, model 2, magnification 1-10
^FD <ECC><mode>,<payload>^FS ; ECC = H/Q/M/L, mode = A (auto) or M (manual)
^XZ
; Typical production line: high recovery + auto encoding
; ^FDHA,https://zplpdf.com^FS| Parameter | Description | Valid values | Default |
|---|---|---|---|
| orientation | Rotation of the QR symbol on the label. Use N for shipping labels, R when stacking content vertically. | N, R, I, B | N |
| model | QR model. Always use 2 in new designs. Model 1 is the legacy 1994 spec and most modern scanners only target model 2. | 1, 2 | 2 |
| magnification | Module (dot) size multiplier. Each unit adds ~5 dots per module at 203 dpi. Bigger value = larger and more scannable QR but takes more label space. | 1–10 | based on dpi |
| ECC override | Optional error-correction override on the ^BQ command itself. In practice this slot is left blank and the level is chosen via the first character of ^FD (H/Q/M/L) — see Field Data Format. | H, Q, M, L | blank (use ^FD prefix) |
| mask value | Optional bit-pattern mask that improves scanner readability when the natural payload produces uniform regions. Almost never needs to be set manually. | 0–7 | 7 |
The ^FD payload for ^BQ always starts with two characters before the comma: the first is the error-correction level (H, Q, M or L) and the second is the input mode (A for automatic encoding selection, M for manual segments where you label encoding per segment with N/A/B/K prefixes). The four cards below show the combinations you will reach for in production. Picking the right one is the single biggest decision — most production bugs come from misreading these two characters.
~30% damage recovery and automatic encoding selection. The safest choice for shipping, freight and outdoor labels where the QR may get scuffed.
^FO50,50^BQN,2,6^FDHA,https://zplpdf.com/track/A-7782^FS~15% recovery — the best balance of capacity and recoverability for clean indoor labels (office, retail price tags, e-commerce).
^FO50,50^BQN,2,6^FDMA,SKU:COF-ORG-250^FS~7% recovery, the densest encoding. Use only when the payload is long and the label is printed indoors at high resolution.
^FO50,50^BQN,2,6^FDLA,<long-url-with-many-query-params>^FSManual mode lets you tag encoding per segment with N (numeric), A (alphanumeric), B (byte) or K (Kanji) prefixes inside the data. Use only when auto mode produces a suboptimal encoding.
^FO50,50^BQN,2,6^FDHM,N0123456789AABC1234^FSReed–Solomon error correction lets the QR code stay readable when part of the symbol is missing or damaged. The trade-off is capacity: higher levels add more redundancy and leave less room for actual data. The level is selected by the first character of the ^FD prefix — HA for high + auto, MA for medium + auto, and so on. There is no implicit default — you always state the level explicitly. For shipping and outdoor use, HA is the recommended starting point; for clean indoor labels MA saves space.
| Level | Recovery | When to use |
|---|---|---|
| L | ~7% | Maximum capacity, clean indoor labels, marketing posters with high-res print. |
| M | ~15% | General-purpose default. Good balance for office, retail, eCommerce labels. |
| Q | ~25% | Thermal labels exposed to wear (warehouses, freight) and slightly soiled environments. |
| H | ~30% | Outdoor labels, food/cold-chain, anywhere the QR may get scratched, smudged or partly torn. Select with the HA, prefix. |
QR size in ZPL is controlled by the magnification parameter (1–10) — there is no ^BY step for QR codes. Each unit multiplies the module (the smallest square in the QR) by 4 dots at 203 dpi and 6 dots at 300 dpi. The total symbol size depends on the magnification and on the payload length (more data → more modules → bigger code).
Each example below is a complete ^XA..^XZ block. Paste into the ZPLPDF viewer to render exactly what your printer will produce.
The 90% case: a QR code that opens a tracking URL when scanned with any smartphone camera. HA, gives high error correction (~30% recovery) plus automatic encoding selection — the safe default for any shipping or e-commerce label.
^XA
^CI28
^FO50,50
^BQN,2,6
^FDHA,https://zplpdf.com/track/A-7782^FS
^XZStores a full contact (name, phone, email, organization) so scanning the label adds the contact to a smartphone. Uses MA, (medium recovery + auto) and magnification 7 to keep ~250 characters scannable.
^XA
^CI28
^FO50,50
^BQN,2,7
^FDMA,BEGIN:VCARD\nVERSION:3.0\nN:Doe;Jane\nFN:Jane Doe\nORG:ZPLPDF Inc.\nTEL:+1-555-0142\nEMAIL:jane@zplpdf.com\nEND:VCARD^FS
^XZEncodes (01) GTIN + (17) expiry + (10) batch in a single QR code following GS1 Digital Link conventions. Common in pharma traceability — HA, gives the high recovery the standard expects.
^XA
^CI28
^FO50,50
^BQN,2,6
^FDHA,https://id.gs1.org/01/07640123456789/17/270930/10/B25C-0481^FS
^XZScanning the QR auto-joins the device to a WiFi network. Use this on packaging or event badges. MA, (medium + auto) is enough for clean indoor labels.
^XA
^CI28
^FO50,50
^BQN,2,6
^FDMA,WIFI:T:WPA;S:Office-Guest;P:Welcome2026;;^FS
^XZWhen the label may get scratched, soiled or partly torn (cold-chain, freight, harsh logistics), bump the magnification and keep the HA, prefix so the QR survives partial damage.
^XA
^CI28
^FO50,50
^BQN,2,8
^FDHA,FREIGHT-A-7782^FS
^XZNon-ASCII characters (中文, ñ, ç, é) require ^CI28 inside the format so the printer treats the payload as UTF-8. MA, (medium + auto) handles the byte segments transparently; without ^CI28 you'll get ? glyphs in the data.
^XA
^CI28
^FO50,50
^BQN,2,6
^FDMA,顾客订单 #A-7782\nNombre: Juana Pérez^FS
^XZQR prints but no scanner can read it.
→ Magnification too low for the data payload — modules end up smaller than the scanner's minimum.
✓ Increase magnification by 2 (e.g., 5 → 7) and confirm the module is at least 0.4 mm wide.
Scanner reads but UTF-8 characters appear as ?.
→ Missing ^CI28 before ^BQ — the default code page strips non-ASCII bytes.
✓ Add ^CI28 right after ^XA. The HA,/MA, automatic input mode then handles the UTF-8 bytes correctly.
QR code looks blocky and is rejected by smartphone cameras.
→ Used model 1 (legacy) instead of model 2 in ^BQ.
✓ Use ^BQN,2,<mag> — always 2 in the model slot for new designs.
Long URL prints but fails to scan partially worn labels.
→ Picked a low-recovery ECC level (LA, or MA,) so the QR cannot survive partial damage.
✓ Use HA, (high recovery, ~30% damage tolerance) for any label that may end up scuffed in the field.
Excess whitespace around the QR forces oversized labels.
→ Quiet zone too large because of an explicit ^FO followed by stale ^BY values from a 1D barcode earlier in the format.
✓ Reset ^BY between symbologies or simply position the QR with its own ^FO outside any prior ^BY block.
QR encodes correctly on the viewer but fails on a Datalogic / Honeywell scanner.
→ Industrial imagers often need a minimum module size and quiet zone of 4 modules.
✓ Increase magnification to ≥6 and keep at least 4 modules of margin around the symbol.
Paste any example from this page into our free online ZPL viewer to see the QR rendered exactly as your printer will produce it.