ZPLJetdocs

API Reference

POST/v1/convert

Render ZPL to PDF (default) or PNG. Default returns raw bytes and stores nothing; pass "output": "url" (paid plans) to host the file and get a public link back.

Body parameters

FieldTypeDefaultDescription
zplstringone inputRaw ZPL, maximum 512 KiB of UTF-8 bytes. The engine validates label structure, prefixes, graphics and resource limits.
zplBase64stringone inputCanonical padded base64 of up to 512 KiB of raw ZPL file bytes. Supply exactly one of zpl or zplBase64. Byte input requires native rendering and never falls back.
gs1ItemsarrayomittedComplete GS1 item groups: [{barcodes: [0, 1]}]. Zero-based compiled barcode indices; optional label selects one compiled label. Omit label to check every label separately. Native only; no fallback. Up to 50 groups, 64 barcodes/group and 1024 references total; duplicate/overlapping selections reject.
strictbooleanfalseReject unsupported commands, unavailable fonts/glyphs and lossy Code39/Code93 normalization. Native only; no fallback. Physical printer qualification remains separate.
dpmm6 | 8 | 12 | 248Print density in dots/mm. 8 = 203 dpi, 12 = 300 dpi, 24 = 600 dpi.
widthMmnumber101.6Label width in millimeters (default 4 in).
heightMmnumber152.4Label height in millimeters (default 6 in).
formatpdf | pngpdfOutput format. PNG supports one label per request; use PDF for multi-label ZPL.
outputdata | urldataDelivery mode. "data" returns the raw file bytes and stores nothing (all plans). "url" hosts the file and returns a public link (paid plans only), kept for your account's retention window — set in the dashboard, up to your plan max (Starter 3, Pro 30, Scale 90 days).

Complete GS1 items

Use gs1Items when every selected barcode belongs to the same item. The engine checks required and mutually exclusive AIs across those carriers, independently on each selected compiled label, including serialized variants. Missing references, unsupported carriers or invalid item data reject even with strict: false. Identical print copies reuse validation. Empty groups disable this option.

Supported carriers: GS1 Code 128 mode D, DataBar, EAN/UPC, GS1 Data Matrix and composites. Structured-append fragments need external assembly. Barcode indices exclude text and graphics. The private engine inspection response lists these indices and carrier eligibility.

A successful response includes X-GS1-Validated-Items. Hosted JSON includes gs1ValidatedItems, also preserved on idempotency replay. Updated SDKs reject a missing or inconsistent acknowledgment without retrying. This validates supplied item data; it does not prove every physical carrier was supplied or verify a cryptographic signature.

Warnings and retries

Check X-Warnings and X-Warning-Commands before printing. Hosted JSON includes warningCount, warningCommands, engine and fellBack. X-Render-Engine and X-Engine-Fallback identify the renderer. Strict mode rejects unsupported printable commands; it does not certify resident-font fidelity.

Send a unique Idempotency-Key per conversion and reuse it for retries. Keys are scoped to your account for 24 hours. Identical JSON results replay. Completed data-mode requests return 409 with conversionId because file bytes are not retained. Pending or unknown outcomes also return 409. A new key starts a new conversion and may consume quota; do not automatically replace a key after an ambiguous response. SDK retries preserve the same key.

Example request

curl -X POST https://api.zpljet.com/v1/convert \
  -H "X-API-Key: zpl_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "zpl": "^XA^FO50,50^A0N,50,50^FDHello^FS^XZ",
    "dpmm": 8,
    "widthMm": 101.6,
    "heightMm": 152.4,
    "format": "pdf"
  }' \
  --output label.pdf

The official SDKs wrap this endpoint with typed params, typed errors, and retries.

Response

With "output": "data" (default), response body is raw application/pdf or image/png bytes, with the conversion id in the X-Conversion-Id header.

With "output": "url", the response is JSON:

{
  "id": "7c9fc824-8d30-4bb9-ba36-03d3bcf574bf",
  "url": "https://files.zpljet.com/…/file.pdf",
  "pages": 1,
  "retentionDays": 7,
  "expiresAt": "2026-07-08T20:09:22.333Z"
}

url is a public link that works until expiresAt, when the file is deleted.

Status codes

Errors are JSON with structured error object — branch on the stable error.code. See Errors & Limits for every code and context fields.

Statuserror.codeDescription
200—Success. The raw PDF/PNG bytes (output:"data", default), or JSON with a public URL (output:"url").
400invalid_requestInvalid request body — error.param names the offending field.
401missing_api_key · invalid_api_keyMissing or invalid API key.
402quota_exceededMonthly quota exceeded — error.resetsAt says when it resets (UTC).
403hosting_not_allowed · no_retention_enforcedHosting not permitted — plan is data-only, or no-retention mode is enforced.
409idempotency_conflict · idempotency_pending · idempotency_completedThis key conflicts, is pending, or already completed a data-mode conversion. See retry handling below.
413payload_too_largeRequest body exceeded the 1 MiB transport limit.
429rate_limit_exceededRate limit exceeded — error.retryAfter (seconds) and error.retryAt (UTC timestamp) say when to retry; the Retry-After header carries the seconds.
502conversion_failedThe rendering engine failed to process the ZPL — error.conversionId identifies the attempt for support.
503service_unavailableService busy or unavailable. Refunds are attempted for unavailable renders; keyed results are retained.

Full machine-readable spec: OpenAPI 3.1.