ZPL Command Reference: ^BQ (QR Code Barcode)

The ^BQ ZPL command tells a Zebra printer to render a QR Code barcode at a specific position on the label. In Label Toolkit's browser-based ZPL designer you can generate and preview ^BQ output instantly without installing any software or sending a test print. The command takes five parameters that control orientation, model, magnification, error correction, and a mask value, and it pairs with ^FD to supply the data.

• ^BQ is the sole ZPL II command for QR Code symbology and supports both Model 1 (legacy) and Model 2 (current standard, up to 4,296 alphanumeric characters).
• Error correction level H (30% recovery) is the right choice whenever a logo or overlay will cover part of the code; level L (7%) maximizes data density when the code will be protected.
• The magnification factor (parameter 3) is the easiest way to resize a QR code; each step equals one printer dot, so at 203 dpi a factor of 5 produces modules that are roughly 1.24 mm (0.049 in) wide.
• Label Toolkit can export finished labels as ZPL or vector PDF, so you can prototype the design in the browser and send exact ZPL to any Zebra device.

What is QR Code and why does it matter for ZPL labels?

QR Code (Quick Response Code) is a 2D matrix symbology invented by DENSO WAVE in 1994. Unlike 1D barcodes such as Code 128, a QR code stores data in both dimensions, which lets it hold URLs, serialized identifiers, GS1 Digital Link URIs, and plain text in a compact square that camera-based scanners and smartphones can read from any angle. For e-commerce, asset tracking, and product traceability labels, QR codes are often the preferred choice over linear barcodes because they survive partial damage (thanks to Reed-Solomon error correction) and can encode enough characters for a full HTTPS URL.

The ISO/IEC 18004 standard governs QR Code symbol structure, version sizing, and error correction.
Source: ISO/IEC 18004:2015 on iso.org

DENSO WAVE, the original inventor, maintains authoritative documentation on QR Code specifications.
Source: QR Code.com by DENSO WAVE

Full ^BQ syntax

The command signature, taken directly from the Zebra ZPL Programming Guide, is:

^BQa,b,c,d,e

How to pair ^BQ with ^FD: data format rules

The ^BQ command defines the symbol style; the actual content comes from ^FD (Field Data). QR Code ^FD strings follow a specific prefix convention that the printer uses to determine encoding mode:

In practice, most e-commerce and asset-tracking labels use automatic mode. Set parameter d to QA or HA (error correction level + A for auto), and the printer handles encoding selection.

Step-by-step: printing a QR code with ^BQ

1. Open a label format with ^XA and set label dimensions using ^PW (print width) if needed.
2. Position the field using ^FO. For example, ^FO50,50 places the top-left corner of the QR code 50 dots right and 50 dots down from the label home position.
3. Call ^BQ with your chosen parameters. A good starting point for most 4-inch labels at 203 dpi is ^BQN,2,5,QA: normal orientation, Model 2, magnification 5 (5 dots per module = 0.625 mm), Q-level error correction, auto mode.
4. Add field data with ^FD. The string must end with ^FS to close the field.
5. Close the label with ^XZ to trigger printing.

Copy-paste ZPL examples

Example 1: URL QR code on a 4 x 2 inch shipping label (203 dpi)

^XA
^PW812
^LL406
^FO30,30
^BQN,2,5,QA
^FDQA,https://labeltoolkit.com^FS
^XZ

What this produces: a QR code whose modules are 5 printer dots wide (5 / 203 in = 0.0246 in = 0.625 mm). At Q-level error correction and a short URL, the symbol will be approximately Version 4 (33x33 modules), making the printed square about 20 mm (0.79 in) on each side including the 4-module quiet zone. The quiet zone (the mandatory blank border around a QR code) must be at least 4 modules wide on all sides per ISO/IEC 18004; at magnification 5 on a 203 dpi printer that equals 20 dots (2.5 mm), so position your ^FO accordingly.

Example 2: Asset tag with H-level error correction (300 dpi printer)

^XA
^PW1200
^LL600
^FO40,40
^BQN,2,4,HA
^FDHA,ASSET-2025-00142^FS
^CF0,28
^FO40,420
^FDHASSET-2025-00142^FS
^XZ

Here magnification 4 at 300 dpi (11.8 dpmm) gives modules that are 4/300 in = 0.34 mm wide. H-level error correction means up to 30% of the symbol can be obscured or damaged and scanners will still recover the data, which is ideal for metal asset tags that may get scratched. The human-readable text is printed beneath using ^CF (font) and a second ^FD / ^FS pair.

Example 3: GS1 Digital Link URI (e-commerce / product traceability)

^XA
^PW812
^LL406
^FO30,30
^BQN,2,6,MA
^FDMA,https://id.gs1.org/01/09521234543213^FS
^XZ

GS1 Digital Link encodes a GTIN inside a standard HTTPS URL so both legacy barcode scanners and smartphone cameras resolve product information. Magnification 6 at 203 dpi produces 0.75 mm modules, comfortably readable by most fixed-mount and handheld scanners.

Choosing the right magnification for your printer resolution

Magnification is the most common source of QR code scan failures. If modules are too small relative to the scanner's optical resolution, the code will fail. As a practical rule, each module should be at least 2 dots wide (and ideally 3 or more for reliable omnidirectional scanning).

Note: these sizes are per module (one dark or light square). The total symbol size equals module size times (version number of modules + 8 modules for quiet zone). A Version 3 QR code is 29x29 modules; at mag 4 on a 203 dpi printer the symbol including quiet zone is (29+8) x 0.50 mm = 18.5 mm square.

Error correction levels in practice

Choosing an error correction level is a trade-off between data capacity and resilience. Higher error correction means the symbol holds more redundancy data, which increases the version (and thus physical size) for the same payload.

When you add a logo to the center of a QR code (a popular branding technique), that logo physically obscures codewords. You must use H-level error correction and keep the logo to under 30% of the symbol area. Label Toolkit's styled QR code generator handles this automatically. See the article on QR codes with a logo and custom styling for the exact design rules.

How ^BQ compares to ^BC (Code 128) and other barcode commands

If you are choosing between a QR code and a 1D barcode for your label, the decision usually comes down to data volume and scanning environment. For a deeper walk-through of the ^BC command specifically, the article on the ^BC Code 128 ZPL command covers its parameter set in the same format used here.

Troubleshooting ^BQ scan failures

Code prints but will not scan

The most common cause is a magnification factor that is too low. At 203 dpi, magnification 1 produces modules that are one dot (0.125 mm) wide, which is below the optical resolution of most scanners. Increase the magnification to at least 3. If the code still fails, check that the quiet zone is intact: ensure the ^FO x-coordinate is at least (4 x magnification) dots from the label edge.

Printer ignores ^BQ and prints nothing

Verify that the data string in ^FD does not contain characters invalid for the chosen encoding mode. In manual mode (M prefix), some control characters require special escape sequences. Switching to automatic mode by appending A to the error correction parameter (e.g. QA instead of Q) usually resolves encoding failures.

QR code looks correct on screen but prints distorted

A mismatch between the ^PW (print width in dots) and the actual media width can cause the printer to clip or re-flow the label. Confirm your print width matches the media: a 4-inch label at 203 dpi is 812 dots; at 300 dpi it is 1,200 dots.

Using ^BQ inside Label Toolkit

Label Toolkit renders a live preview of any ZPL you write, including ^BQ, directly in the browser. You can start from a blank canvas, drag and position a QR code element, and export the result as ZPL to send to a Zebra printer, or as a vector PDF for desktop or commercial printing. The ZPL export reflects the exact ^BQ parameters the printer will receive, so what you see in the preview is what prints.

If you already have a ZPL file containing ^BQ commands, the ZPL import tool parses the file back into an editable label you can modify visually without touching the raw ZPL. For the broader context of how ^BQ fits into a full ZPL label format alongside ^XA, ^FO, ^FD, and ^FS, the ZPL commands complete reference hub covers every major command in one place.

Frequently asked questions

What does ^BQ stand for in ZPL?

^BQ stands for Barcode QR Code. In the ZPL II naming convention, ^B introduces a barcode command and the following letter or letters identify the symbology. ^BC is Code 128, ^BQ is QR Code, and so on. The Zebra ZPL Programming Guide lists the full set.

How do I make a larger QR code with ^BQ?

Increase the magnification parameter (the third value in ^BQ). At 203 dpi, changing from magnification 3 to magnification 6 doubles each module from 0.375 mm to 0.75 mm, which roughly doubles the printed size of the symbol. Do not change the label font size; that has no effect on ^BQ.

What is the maximum data a ^BQ QR code can hold?

Using Model 2 with L-level error correction, the QR Code specification supports up to 7,089 numeric digits, 4,296 alphanumeric characters, or 2,953 bytes of binary data. In practice, keep URLs under about 100 characters so the resulting symbol stays compact enough to print reliably on small labels.

Can I print a QR code with a logo using ^BQ?

Not directly with ZPL alone: ^BQ generates the QR matrix but cannot overlay an image. The standard approach is to generate the QR code at H-level error correction (30% recovery), then print a graphic using ^GF or ^XG on top at the center. Label Toolkit's designer handles this in the browser without manual ZPL editing; see the guide on QR codes with logos for details.

Does ^BQ support GS1 Digital Link?

Yes. A GS1 Digital Link URI is simply an HTTPS URL that follows a structured path convention (for example, https://id.gs1.org/01/09521234543213 for a GTIN). Pass the full URL as the ^FD string in automatic mode (parameter d ending in A) and the printer will encode it as a standard QR Code. GS1 member documentation covers the URI syntax in detail.

Ready to design and preview your first ^BQ label without installing anything? Create a free Label Toolkit account and start generating ZPL QR code labels in your browser right now.