ZPL ^BY Command Examples for Code 128 and GS1-128 Labels

The ^BY command looks small, but it often decides whether a barcode scans quickly or becomes a support ticket. It sets the default module width, wide-to-narrow ratio, and barcode height for supported barcode commands that follow it.

The basic shape

^BYw,r,h

• w: module width in dots.
• r: wide-to-narrow ratio for symbologies that use it.
• h: default barcode height in dots.

For Code 128 labels, teams most often tune width and height.

Example: small product label

^XA
^PW609
^LL305
^FO40,35^A0N,28,28^FDSKU A-1009^FS
^FO40,85^BY2,3,90
^BCN,90,Y,N,N
^FDA-1009-BLACK-M^FS
^XZ

This works when the value is short and the scanner is close. If the SKU grows, the barcode may become too wide before anyone notices.

Example: warehouse label with more room

^XA
^PW812
^LL406
^FO60,50^A0N,34,34^FDCase ID^FS
^FO60,110^BY3,3,130
^BCN,130,Y,N,N
^FDCASE-20260618-000349^FS
^XZ

A wider module is easier to scan on rough media or at a longer distance, but it consumes width. The browser preview tells you if it fits; the scanner tells you if it works.

GS1-128: get the data right first

GS1-128 is not just Code 128 with parentheses. The data needs application identifiers and, for variable-length fields, a separator. ZPL Code 128 supports control sequences, but they are easy to get wrong if you type them by memory.

^XA
^PW812
^LL406
^FO50,40^A0N,30,30^FDGS1 case label^FS
^FO50,105^BY2,3,130
^BCN,130,Y,N,N
^FD>;>801095011015300031726063010LOT42^FS
^FO50,270^A0N,24,24^FD(01)09501101530003 (17)260630 (10)LOT42^FS
^XZ

Use GS1 Data Parser to check the readable data, then use GS1 Barcode Helper or Barcode Generator for a safer starting point.

Separate three reviews: data, layout, print

When a GS1 barcode fails, teams often jump straight to printer darkness. That is sometimes the issue, but it is not the first thing to check. Split the work into three reviews so the conversation stays clear.

1. Data review: parse application identifiers, dates, batch values, serial values, and variable-length separators with GS1 Data Parser.
2. Layout review: preview the label and inspect whether the barcode fits inside ^PW with enough quiet zone.
3. Print review: print on the target Zebra printer and scan with the same device used at receiving, packing, or production.

This separation matters because each failure has a different owner. Business systems usually own GS1 data. Label templates own layout. Operations owns printer condition, media, and scanner setup.

A quick receiving-dock test

Before releasing a GS1-128 label, print three labels with different data lengths: a short lot, a long lot, and a serial value that is close to the longest value your system allows. This catches layout failures that a single demo value hides.

Short lot:  (01)09501101530003 (17)260630 (10)L42
Long lot:   (01)09501101530003 (17)260630 (10)LOT-2026-JUNE-LINE-04
Serial:     (01)09501101530003 (21)SN000000000000839102

Scan each label into the same receiving or WMS screen operators use. If the scanner output shows literal parentheses, missing separators, or a value split into the wrong application identifier, the problem is data encoding, not ^BY. If the data is correct but scans slowly, return to module width, quiet zone, darkness, and speed.

A minimal GS1 debug label

For vendor support or an internal bug report, remove everything except the barcode and human-readable line. That keeps private shipment data out of the conversation and makes it obvious whether the encoded value is the problem.

^XA
^CI28
^PW812
^LL320
^FO50,50^BY3,3,120
^BCN,120,Y,N,N
^FD>;>801095011015300031726063010LOT42^FS
^FO50,210^A0N,26,26^FD(01)09501101530003 (17)260630 (10)LOT42^FS
^XZ

If this minimal label scans correctly, reintroduce the surrounding label elements one by one. The failure is likely quiet zone, clipping, DPI conversion, or a neighboring graphic. If it fails, stay focused on data encoding, scanner configuration, and barcode module width.

Common ^BY mistakes

• Using ^BY1 on thermal labels because it “fits better”. It often scans worse.
• Scaling a label to 300 DPI but forgetting to review ^BY.
• Letting the barcode run into a logo, text block, or label edge.
• Testing with short demo data while production values are much longer.
• Printing too dark, which makes narrow spaces close up.

When in doubt, create two samples: one with ^BY2 and one with ^BY3. Print both on the real printer and scan them at the real working distance. That five-minute test is better than a week of guessing.