Printing saved designs

Writing label layouts as JSON is fine for simple tags, but for anything designed — logos, precise placement, fonts — it’s easier to lay the label out in the editor once and drive it from your server.

1. Design and save

Build the label in the editor, putting {{placeholders}} wherever data changes:

• Text: Ship to: {{name}}
• A barcode’s value: {{sku}}

Then account menu → Save to cloud.

2. Find its id

curl https://barcodestack.com/api/v1/designs \
  -H "Authorization: Bearer bcs_live_…"

{
  "count": 1,
  "designs": [
    { "id": "d_9f2c…", "name": "Product tag", "presetId": "thermal-2x1",
      "updatedAt": "2026-08-27T04:12:00.000Z" }
  ]
}

3. Render it with data, then review

curl --fail --output label.zpl --dump-header label-headers.txt \
  -X POST https://barcodestack.com/api/v1/designs/d_9f2c…/render \
  -H "Authorization: Bearer bcs_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "name": "SAMPLE RECIPIENT", "sku": "SAMPLE-SKU" } }'

Check the HTTP status, Content-Type and X-Conversion-Warnings before using the file. Confirm destination, dimensions, DPI and physical copy count; inspect the converted output and authorize a one-label test. The API returns a file; it does not send a job to your printer. Never forward an unchecked response or retry a job automatically after uncertain delivery.

Example rows within request/work limits:

{ "rows": [{ "sku": "SAMPLE-001" }, { "sku": "SAMPLE-002" }] }

"copies": 3 requests three physical copies of each row. Rows times copies must fit the 100-label API job limit, and other workload limits also apply. Replace sample values with authorized data and confirm the total before printing.

What converts, and what doesn’t

The design is translated into native printer commands:

Editor element	Prints as
Text and text boxes	^A0 scalable text, wrapped with ^FB
Barcodes	Native symbology commands (^BC, ^BE, ^BX…)
QR codes	^BQ
Rectangles, lines, tables	^GB boxes and rules
Images and photos	Skipped — reported in X-Conversion-Warnings
A barcode with no ZPL II command	Refused — the whole request fails with 422 unrepresentable_element

Barcode module widths are matched to the footprint the design gave them, so printed symbols come out close to the size you laid out. GS1 DataBar Expanded is the exception: ^BR sizes its own height from the module width, so it can print shorter than the box you drew — you’ll get a warning saying so.

A skipped photo leaves a gap you can see. A skipped barcode leaves a label that looks finished with nothing to scan, so the render is refused instead. For either, consider the editor’s local export or PDF path, review its separate conversion warnings and test the result. Local ZPL uses supported native commands and selected raster fallbacks; it is not simply a bitmap of the whole label.

Check the conversion

To see exactly how a design maps before printing:

curl https://barcodestack.com/api/v1/designs/d_9f2c…/render \
  -H "Authorization: Bearer bcs_live_…"

On success that’s 200 with { "spec": …, "warnings": […] } — the converted element list plus anything that was skipped. If a barcode can’t be drawn you get 422 instead, carrying error, message, an errors array naming each offending barcode, and the partial spec so you can still see what converted.

Cloud saves transmit design content and saved rows to the service. Each free account has 10 cloud designs, 9 MB total payload storage, a 900,000-byte maximum per design and 3 API keys sharing account limits. Keep keys in a secret store; use synthetic values when exploring the reference. See the API quickstart and Privacy Policy.