API Reference
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
| Field | Type | Default | Description |
|---|---|---|---|
| zpl | string | one input | Raw ZPL, maximum 512 KiB of UTF-8 bytes. The engine validates label structure, prefixes, graphics and resource limits. |
| zplBase64 | string | one input | Canonical 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. |
| gs1Items | array | omitted | Complete 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. |
| strict | boolean | false | Reject unsupported commands, unavailable fonts/glyphs and lossy Code39/Code93 normalization. Native only; no fallback. Physical printer qualification remains separate. |
| dpmm | 6 | 8 | 12 | 24 | 8 | Print density in dots/mm. 8 = 203 dpi, 12 = 300 dpi, 24 = 600 dpi. |
| widthMm | number | 101.6 | Label width in millimeters (default 4 in). |
| heightMm | number | 152.4 | Label height in millimeters (default 6 in). |
| format | pdf | png | Output format. PNG supports one label per request; use PDF for multi-label ZPL. | |
| output | data | url | data | Delivery 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.pdfThe 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.
| Status | error.code | Description |
|---|---|---|
| 200 | — | Success. The raw PDF/PNG bytes (output:"data", default), or JSON with a public URL (output:"url"). |
| 400 | invalid_request | Invalid request body — error.param names the offending field. |
| 401 | missing_api_key · invalid_api_key | Missing or invalid API key. |
| 402 | quota_exceeded | Monthly quota exceeded — error.resetsAt says when it resets (UTC). |
| 403 | hosting_not_allowed · no_retention_enforced | Hosting not permitted — plan is data-only, or no-retention mode is enforced. |
| 409 | idempotency_conflict · idempotency_pending · idempotency_completed | This key conflicts, is pending, or already completed a data-mode conversion. See retry handling below. |
| 413 | payload_too_large | Request body exceeded the 1 MiB transport limit. |
| 429 | rate_limit_exceeded | Rate limit exceeded — error.retryAfter (seconds) and error.retryAt (UTC timestamp) say when to retry; the Retry-After header carries the seconds. |
| 502 | conversion_failed | The rendering engine failed to process the ZPL — error.conversionId identifies the attempt for support. |
| 503 | service_unavailable | Service busy or unavailable. Refunds are attempted for unavailable renders; keyed results are retained. |
Full machine-readable spec: OpenAPI 3.1.