Migration checklist

Work through this in order. Most integrations clear it in well under an hour; the time sink (if any) is usually step 4.

1. Get access

• Create an API key.
• Pick the right scope for the key: PNG only, PDF only, or all formats — match what your integration actually requests via Accept.

2. Swap the base URL and add the key

• Change https://api.labelary.com to https://api.zpl.tools/compatibility/labelary/ everywhere it's hardcoded (or in the one config value if you already parameterized it — you did parameterize it, right?).
• Add X-API-Key: <your key> to every request. There's no unauthenticated fallback — a missing key is a 401.
• Re-run your existing test suite / a few manual calls against the new base URL and confirm you get back the same shapes (PNG bytes, PDF bytes, X-Total-Count header) you did against Labelary.

3. Check for headers and formats you rely on

Grep your integration for Accept, X-Rotation, X-Quality, X-Page-, and X-Label-Border — then check each against Behavioral differences:

• If you request Accept: application/json, or any of epl/ipl/dpl/sbpl/pcl5/pcl6 — stop, these aren't implemented. Contact us before migrating that call.
• If you send X-Rotation with Accept: application/pdf — rotation only applies to PNG today. Either switch that call to PNG, or hold off on migrating it.
• If you send X-Page-Size/X-Page-Layout/etc. and your downstream consumer depends on the actual PDF page size or a multi-label grid layout (not just that the request succeeds) — these headers are validated but not yet composed into the PDF. Verify the output visually before trusting it in production.
• Otherwise: no changes needed, these headers behave the same way.

4. Validate rendering on real workloads

• Take a representative sample of the ZPL you actually send in production (not just a "Hello World" label) and render it through both Labelary and zpl.tools.
• Compare visually — barcodes, fonts, field positioning. Both engines aim for the same output but aren't bug-for-bug identical; see the compatibility notes for known differences.
• If you use X-Linter: On for warnings, confirm the warning classes you depend on are covered — see the Linting reference.

5. Update error handling

• If your error handling matches on exact response text, review the error reference — most messages match Labelary closely but not always byte-for-byte.
• Add handling for the zpl.tools-specific 401/403/429 JSON error envelope (Labelary has no direct equivalent since its free tier needs no key).
• Drop any Labelary-rate-limit backoff logic if you had it — or leave it in for now, it's harmless.

6. Cut over

• Flip traffic (all at once, or gradually if your infra supports it).
• Watch error rates for the first batch of real traffic.
• Decommission the Labelary integration once you're confident.

Need help?

For higher-volume migrations we offer a founder-led concierge migration — free engineering time to map your integration, plus a discounted first month while you validate. Contact us and mention you're migrating from Labelary.