FedEx ZPL labels: request, preview and fix

Published: 2026-09-14

Printer resolution

Result

Ask the FedEx Ship API for a thermal label and it returns ZPL, base64-encoded, inside the JSON of the shipment response. Which ZPL you get — the label size, whether a doc tab is attached and, above all, which print density the dots are written for — is decided by a handful of request fields. This page lists those fields, shows where the label sits in the response and walks through the checks worth running before the file reaches a printer. The rules that apply to every carrier label (do not edit it, print your own data separately) are in working with carrier ZPL labels; this page is the FedEx-specific layer on top. The UPS counterpart is UPS ZPL labels.

Field names and values below were read from FedEx's published Ship API reference on 2026-09-14. They change between API versions; confirm them against the current reference before you rely on them. Labelixa is not affiliated with FedEx — this is a workflow description, not an integration.

The request fields that shape the ZPL

Everything that matters sits in labelSpecification inside the requested shipment of a POST /ship/v1/shipments call:

imageType — ZPLII for a Zebra data stream. The other values are EPL2, PDF and PNG; only the first two are thermal formats.
labelFormatType — COMMON2D returns a complete label. LABEL_DATA_ONLY returns barcode data for a label you draw yourself and is a different workflow.
labelStockType — STOCK_4X6 for plain 4×6 inch stock. The doc-tab variants (STOCK_4X675_LEADING_DOC_TAB, STOCK_4X675_TRAILING_DOC_TAB, STOCK_4X9_LEADING_DOC_TAB, STOCK_4X9_TRAILING_DOC_TAB, STOCK_4X85_TRAILING_DOC_TAB, STOCK_4X105_TRAILING_DOC_TAB) and the tall plain stocks (STOCK_4X8, STOCK_4X9) are physically longer than 6 inches — the label you get back is written for that length.
resolution — 203 or 300. The reference states that the default is 203 and that 300 is only allowed with ZPLII. This one field decides how every coordinate in the file is to be read.
Optional: labelRotation (NONE, LEFT, RIGHT, UPSIDE_DOWN) and labelPrintingOrientation (TOP_EDGE_OF_TEXT_FIRST, BOTTOM_EDGE_OF_TEXT_FIRST) apply to roll-stock thermal output; labelOrder puts the shipping label first or last when several documents are produced.

"labelSpecification": {
  "labelFormatType": "COMMON2D",
  "imageType": "ZPLII",
  "labelStockType": "STOCK_4X6",
  "resolution": 203
}

Where the label is in the response

The label is not at the top level. The path is output.transactionShipments[].pieceResponses[].packageDocuments[]: one piece response per package, and inside it one or more package documents, each carrying encodedLabel (the base64 payload) next to docType, contentType, trackingNumber and copiesToPrint. A url field may accompany the document; decoding encodedLabel yourself keeps the ZPL under your control.

jq -r '.output.transactionShipments[0].pieceResponses[0].packageDocuments[0].encodedLabel'    response.json | base64 -d > label.zpl
grep -c '\^XA' label.zpl     # number of label formats in the buffer

Count the formats. The reference notes that all labels required for a shipment are generated and returned in a single buffer, so one decoded document can contain more than one ^XA … ^XZ block — a service label after the shipping label, for example. A printer prints all of them; the preview endpoint returns one format per index, or all of them as a PDF when the index is left out.

Preview at the density you asked for

ZPL has no resolution header: the dots in the file are read at the printer's own density. A file requested with resolution: 300 and previewed at 8 dots/mm looks about one and a half times too large and runs off the label; the same file at 12 dots/mm is correct. Match the preview to the request — 8dpmm for 203, 12dpmm for 300 — and give the stock length you asked for (6, 6.75, 8, 9 …).

curl -X POST "https://api.labelixa.com/v1/printers/8dpmm/labels/4x6/0"      --data-binary @label.zpl --output label-0.png
curl -X POST "https://api.labelixa.com/v1/printers/8dpmm/labels/4x6/1"      --data-binary @label.zpl --output label-1.png   # second format, if any

If you no longer know which resolution a stored file was generated for, the size and DPI analyzer reads the declared width and length out of the file and reports the density that makes them a standard label size — or says that it cannot tell.

Checks worth running before printing

Density matches the printer. The reference gives the FedEx 1D barcode an X-dimension of 3 dots at 203 dpi and 4 dots at 300 dpi. Send a 203-dpi file to a 300-dpi head and those 3-dot bars shrink to two thirds of the intended width — the label looks fine at arm's length and fails at the scanner.
Stock matches the media. A doc-tab stock is 6.75 inches or longer; on plain 6-inch media the tab lands on the next label or is cut off. Preview at the requested length and compare with the media you actually load.
No error-level findings. Run the file through diagnostics and queue it only when there are no errors; warnings are worth logging.
Nothing edited. The tracking barcode, routing block and service markings must reach the printer as generated. Add your own data as a separate label, not by editing FedEx's format.

curl -X POST "https://api.labelixa.com/v1/diagnostics?dpmm=8&w=4&h=6"      --data-binary @label.zpl

The same gate runs from a shell or CI as npx labelixa validate label.zpl, which exits non-zero on error-level findings. The reference also names the thermal printers FedEx recommends for the API — among the ZPL models the GK420, the ZT410 and other ZT4xx series printers — a useful sanity check when a warehouse fleet is mixed.

Failures that look like FedEx problems but are not

Label prints at two-thirds size with a wide margin. The file was generated for 203 dpi and printed on a 300-dpi head (or the reverse: it overflows and clips). Fix the request's resolution or the printer, not the file.
An extra, mostly blank label after each shipment. A doc-tab or 8/9-inch stock was requested and the media is 6 inches; or the buffer contained a second format you did not expect. The format count above tells you which.
Output is rotated. Compare paper with preview. If the preview is rotated too, the request's labelRotation or orientation did it; if only the paper is, the printer's own orientation setting is the cause — see label prints upside down.
Only the shipping label printed. Multi-package shipments return one piece response per package; loop over all of them, and over every package document inside each.

Frequently asked questions

Which FedEx request field decides the density of the ZPL?

labelSpecification.resolution — 203 or 300. The reference gives 203 as the default and allows 300 only with imageType ZPLII. Preview at 8 dots/mm for 203 and 12 dots/mm for 300.

Where is the ZPL in the FedEx shipment response?

In output.transactionShipments[].pieceResponses[].packageDocuments[].encodedLabel, base64-encoded, one piece response per package. One decoded document can hold more than one ^XA…^XZ format, because all labels for a shipment come back in a single buffer.

Why does the FedEx label print at two-thirds size?

The file was generated for 203 dpi and printed on a 300 dpi head (or previewed at the wrong density). Change resolution in the request or use a matching printer; do not edit the file.

Related guides

What is ZPL?

ZPL is the language Zebra thermal printers understand. How to read the commands, how a label is put together, and the most common mistakes.

Which barcode symbology should I use?

EAN-13, Code 128 or QR? Practical rules for picking a barcode based on your data, your space and the scanner that has to read it.

How to preview a ZPL file without a printer

A ZPL file is just text — the label only exists once something draws it. Three practical ways to see a ZPL label before it reaches the printer.

Try your own ZPL code →