Migration checklist

Do these steps in order.

1. Get access

• Create an API key.
• Select the scope for the key: PNG only, PDF only, or all formats.
• Match the scope to the formats your integration requests with Accept.

2. Change the base URL and add the key

• Change https://api.labelary.com to https://api.zpl.tools/compatibility/labelary/ in each location where it is hardcoded, or in the one configuration value.
• Add X-API-Key: <your key> to every request. The API returns a 401 for a request with no key.
• Run your test suite, or a few manual calls, against the new base URL.
• Confirm that the responses have the same shape as the Labelary responses: PNG bytes, PDF bytes, and the X-Total-Count header.

3. Check the headers and formats that you use

Search your integration for Accept, X-Rotation, X-Quality, X-Page-, and X-Label-Border, and check each against Behavioral differences.

• If a request asks for an unimplemented format (Accept: application/json, or epl/ipl/dpl/sbpl/pcl5/pcl6), contact us before you migrate it.
• If a request sends X-Rotation with Accept: application/pdf, change it to PNG or do not migrate it yet.
• If a consumer depends on the PDF page size or a multi-label grid layout, examine the PDF before production use.
• For the other headers, make no changes. They behave the same way.

4. Validate the render output on real workloads

• Render a representative sample of the production ZPL, not only a "Hello World" label, through both Labelary and zpl.tools.
• Compare the two outputs visually: barcodes, fonts, and field positions.
• See the compatibility notes for the known differences between the two engines.
• If you use X-Linter: On for warnings, confirm that the API reports the warning classes you use. See the Linting reference.

5. Update your error-handling code

• If your code matches on the exact response text, review the error reference. Most messages are close to Labelary's, but not all are identical.
• Add code for the zpl.tools JSON error envelope for 401, 403, and 429. Labelary has no equivalent.
• Remove the backoff logic for the Labelary rate limits.

6. Change production traffic

• Change the traffic to zpl.tools, all at once or in stages.
• Monitor the error rates for the first batch of production traffic.
• Remove the Labelary integration when the new one is stable.

Help with your migration

For a higher-volume migration, zpl.tools offers a founder-led concierge migration. It includes free engineering time to map your integration, and a discounted first month while you validate. Contact us and mention the migration from Labelary.