API quickstart

The BarcodeStack API turns label data into native ZPL — real printer commands, not bitmaps — so responses are bytes rather than megabytes and the printer draws every barcode at its own maximum fidelity.

Full interactive reference: /api/docs (Swagger UI — you can call every endpoint from the page).

1. Create an API key

Open the editor, sign in, then account menu → API keys → Create. The key is shown once:

bcs_live_1a2b3c4d…

Send it as a bearer token on every request:

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

2. Render your first label

curl -X POST https://barcodestack.com/api/v1/labels/render \
  -H "Authorization: Bearer bcs_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "size": { "preset": "thermal-4x6" },
    "elements": [
      { "type": "text", "x": 0.25, "y": 0.3, "text": "SHIP TO", "fontSize": 10 },
      { "type": "text", "x": 0.25, "y": 0.55, "text": "{{name}}", "fontSize": 18, "width": 3.5 },
      { "type": "barcode", "x": 0.4, "y": 4.2, "symbology": "code128",
        "value": "{{tracking}}", "height": 1, "moduleWidth": 3 }
    ],
    "data": { "name": "Jane Doe", "tracking": "1Z999AA10123456784" }
  }'

You get back a ZPL document. Send it straight to a printer:

curl -s -X POST … | nc PRINTER_IP 9100

3. Print a batch

Pass rows and you get one label per row in a single response — the fastest way to print a run:

{
  "size": { "widthIn": 2, "heightIn": 1, "dpi": 203 },
  "elements": [
    { "type": "barcode", "x": 0.1, "y": 0.2, "symbology": "code128", "value": "{{sku}}", "height": 0.5 }
  ],
  "rows": [{ "sku": "ABC-001" }, { "sku": "ABC-002" }, { "sku": "ABC-003" }]
}

Coordinates and sizes

Everything in a spec is in inches, measured from the label’s top-left corner, so the same spec prints correctly at any resolution. Give the size either as a catalog preset id or explicit dimensions:

{ "size": { "preset": "thermal-4x6" } }
{ "size": { "widthIn": 4, "heightIn": 6, "dpi": 203 } }

GET /api/v1/presets lists all 148 sizes; ?search=4x6 or ?brand=dymo narrows it.

Element types

Type	Purpose	Key fields
text	Text, optionally wrapped	text, fontSize (points), width, align
barcode	1D and GS1 symbologies	symbology, value, height, moduleWidth
qr	QR code	value, magnification, ecLevel
box	Rectangle or filled block	width, height, thickness, filled
line	Rule or divider	x2, y2, thickness

{{placeholders}} in any text or value are filled from data (single label) or rows (batch).

Errors

Errors are JSON with a machine-readable code and a message written for a human:

{ "error": "invalid_spec", "message": "ean13 needs 13 digits (or 12 to auto-add the check digit); got 3" }

Status	Meaning
400	The spec or a barcode value is invalid — the message says which
401	Missing or invalid API key
404	No such design for this account
422	A saved design has nothing the printer can draw natively

Next steps

• Printing saved designs — design in the browser, print from your server
• Full API reference