Skip to content
BarcodeStack Docs

API quickstart

The BarcodeStack API turns supported label data into native ZPL commands. Conversion may omit unsupported artwork or reject unsupported barcodes; review warnings and test the result. Response size depends on the content. Verify the exact printer’s resolution, firmware, media and printed output.

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

1. Create an API key

Section titled “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:

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

2. Render your first label

Section titled “2. Render your first label”
Terminal window
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": "SAMPLE — REPLACE RECIPIENT", "tracking": "SAMPLE-NOT-POSTAGE" }
  }'

Save the response to a file using curl --fail --output label.zpl with the request above. Inspect the content and conversion warnings, confirm your printer, DPI and physical label count, then explicitly choose to send that reviewed file to your printer. Do not pipe an unchecked HTTP response directly to a printer or retry automatically after uncertain delivery.

This example is address artwork, not postage or a carrier-issued shipping label. Replace every sample value before actual use.

3. Print a batch

Section titled “3. Print a batch”

Pass rows to render one label per row in a single response, subject to the request, workload and output limits:

{
  "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": "SAMPLE-001" }, { "sku": "SAMPLE-002" }, { "sku": "SAMPLE-003" }]
}

Coordinates and sizes

Section titled “Coordinates and sizes”

Everything in a spec is in inches, measured from the label’s top-left corner. Select your actual printer resolution and test a sample; conversion and firmware limits can affect the output. 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 every size in the catalog; ?search=4x6 or ?brand=dymo narrows it.

Element types

Section titled “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

Section titled “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
413 Input or requested output exceeds a supported size limit
429 Shared account or service capacity is temporarily exhausted

Free usage and data handling

Section titled “Free usage and data handling”

The service is free. Accounts have up to 10 cloud designs, 9 MB total design storage, and 3 API keys. A saved design is limited to 900,000 bytes. API keys share request and work limits at account level; creating more keys does not increase those limits. Split large jobs and handle 413/429 responses without unbounded retries. The interactive API reference describes supported fields.

API inputs leave your device. Render requests process the supplied label and data rows on the server; design-save requests persist a design. Use synthetic values when exploring the interactive documentation. Keep API keys in a secret store, not in URLs, shared documents or AI prompts. See the Privacy Policy.

Next steps

Section titled “Next steps”