ZPL QR Code — The Complete ^BQ Command Guide

What is a ZPL QR code?

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).

^BQ command syntax

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

^BQ parameters

Error correction levels (H / Q / M / L)

Reed–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.

Sizing & magnification

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).

• 203 dpi printer + magnification 5 ≈ 200×200 dots ≈ 25×25 mm with a 50-char URL.
• 203 dpi printer + magnification 8 ≈ 320×320 dots ≈ 40×40 mm — recommended for outdoor scanning at >50 cm.
• 300 dpi printer + magnification 5 ≈ 300×300 dots ≈ 25×25 mm with a 50-char URL.
• Smartphones read magnification 3 reliably if the URL is short (≤25 chars) and the label is held within 20 cm of the camera.
• Always test on the slowest expected scanner first; bumping magnification by 1 is cheaper than failed scans in the field.
• Module size below 0.4 mm becomes unreadable on most low-end imagers — keep magnification ≥4 on 203 dpi printers.

Common QR code errors & how to fix them