Barcode Labels Docs

Saved templates

Design a label once in the Designer, then print it from code with your own values, as PDF, PNG or SVG.

Design a label in the Designer, mark the parts that change as fields, save it, and print it from any code with one request. The API fills in the fields and sends back the finished label.

1. Make a template with fields

  1. Open the Designer and lay out your label.
  2. Select a text or barcode that should change per label. Under Data Source, choose Fields and type a name in braces where the value goes: {SKU} for a barcode, or Lot {Lot} · Exp {Expiry} for text. Each name becomes a field.
  3. Save to your account or an organization (pick it next to the Save button). Templates saved on "This device" can't be reached by the API.
  4. Open ⋯ → Use with API. It shows the template id, its fields and requests ready to copy.

2. Get an API key

Sign in, open Account → API keys & billing (barcodelabels.io/account) and create a key. Send it as Authorization: Bearer bl_live_... with every request. Keep it secret: use it from servers and scripts, not browser code others can read.

3. Print it

Put each field in the query string:

curl -H "Authorization: Bearer $BARCODE_LABELS_KEY" \
  "https://barcodelabels.io/api/v1/templates/5f1c.../render?SKU=A-100&Location=R2-S4" \
  -o label.pdf

That's it. Add format=png or format=svg for an image, and qty=10 for ten copies in one PDF.

GET /api/v1/templates/{id}/render

ParameterDefaultDescription
field name—Any field of the template, e.g. SKU=A-100. Not case-sensitive (sku fills SKU)
formatpdfpdf (sized to the label; one page per label), png (300 DPI) or svg (vector, real label size)
qty1Copies, 1–500. Auto-increment fields count up across the copies. PDF only
space—Only look in personal or org:<id>. Leave it out: the API searches your account, then your organizations
field.<name>—Sets a field named format, qty, quantity or space, e.g. field.qty=12

A field you leave out prints empty, and the response lists it in the X-Missing-Fields header. A name that isn't a field of the template is a 400 unknown_field that lists the valid names.

POST /api/v1/templates/{id}/render

Same thing with a JSON body, for many labels at once or values that are awkward in a URL:

KeyDefaultDescription
values—{ "SKU": "A-100" } for one label
rows—[{ "SKU": "A-100" }, { "SKU": "A-101" }]: one label per row (instead of values)
quantity1Copies of each row (qty works too). rows × quantity ≤ 500
formatpdfpdf, png or svg. PNG and SVG return one label
space—As above
curl -X POST -H "Authorization: Bearer $BARCODE_LABELS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows": [{"SKU": "A-100"}, {"SKU": "A-101"}, {"SKU": "A-102"}]}' \
  https://barcodelabels.io/api/v1/templates/5f1c.../render -o labels.pdf

From JavaScript:

const res = await fetch(`https://barcodelabels.io/api/v1/templates/${id}/render`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.BARCODE_LABELS_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ values: { SKU: 'A-100' }, format: 'png' }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const png = Buffer.from(await res.arrayBuffer());

With no values at all, the template prints as designed, with its sample text.

GET /api/v1/templates

Lists every template your key can print: your own and those of every organization you belong to (any role, including view-only). Each comes with its fields, their sample values and a renderUrl ready to call. Optional space and search (name contains) filters. GET /api/v1/templates/{id} returns the same for one template.

{
  "spaces": [
    { "space": "personal", "name": "Personal", "permission": "manage" },
    { "space": "org:k3x9...", "name": "Acme Warehouse", "permission": "view" }
  ],
  "templates": [
    {
      "id": "5f1c...",
      "name": "Bin label",
      "space": "org:k3x9...",
      "label": { "width": 2, "height": 1, "unit": "in", "orientation": "landscape" },
      "fields": ["SKU", "Location"],
      "sampleValues": { "SKU": "A-100", "Location": "R2-S4" },
      "renderUrl": "https://barcodelabels.io/api/v1/templates/5f1c.../render?SKU=A-100&Location=R2-S4",
      "updatedAt": "2026-10-31T17:02:11.000Z"
    }
  ]
}

Access and billing

A key prints exactly what its owner can open on barcodelabels.io, checked on every request: leave an organization and its templates stop printing immediately. A PDF counts one label per page toward your allowance; PNG and SVG count 1; listing is free. Responses are Cache-Control: private, no-store. The API always prints the last saved version of a template.

Errors

CodeStatusMeaning
api_key_required401No API key sent. Saved templates always need one
invalid_request, invalid_json400A parameter or the body is invalid; the message says which
unknown_field400A value names a field the template doesn't have; the message lists its fields
too_many_labels400More than 500 labels in one request
one_label_only400PNG and SVG return one label; use format=pdf for several
forbidden403Your role can't use that organization's templates
space_not_found, template_not_found404No such template where your key can see it
ambiguous_template409The id exists in several of your organizations; add space
encode_failed, too_much_text422A barcode can't encode the value given (e.g. letters in an EAN-13), or too much text
templates_unavailable503Temporarily unavailable; retry

See Errors & Rate Limits for the shared codes, plans and limits.

On this page