API reference

LabelCraft - barcode labels for Shopify that print at exactly the size you set.

The LabelCraft API prints labels and reads templates from outside the Shopify admin: a warehouse system, a receiving script, a scheduled job. It is the app's own print engine reached with a key instead of a session, so a label printed through the API is the label the app would have printed for the same template and the same products, warnings included.

It is part of the Warehouse plan. Keys are created in LabelCraft, under Settings, API access.

Authentication

Send the key as a bearer token on every request. Keys start with lc_live_ and are shown once, when created. A shop holds at most 5 active keys; revoking one takes effect on the next request.

A request without a valid key answers 401. A valid key on a shop below the Warehouse plan answers 402.

curl https://labelcraft.tech/api/v1/templates \
  -H "Authorization: Bearer lc_live_0123456789abcdef0123456789abcdef01234567"

Limits

• 60 requests per minute per key. Above that, 429 with a Retry-After header, in seconds.
• 2000 labels per print request, summed over the quantities. Above that, 400 too_many_labels; split the job.
• 500 items (variant and quantity pairs) per print request. Above that, 400 invalid_request with the count in details[].
• A body of at most 1048576 bytes, enough for a template carrying a brand font and a logo. Above that, 413 payload_too_large.
• 200 non-archived templates per shop through POST /templates. Above that, 409 template_limit_reached; archive one or PATCH an existing one.
• The rate window lives in the memory of the single machine that serves the app, so it resets on a deploy. Nothing is queued: a refused request is not printed.
• A print request is not idempotent. If your call times out after the server answered, retrying prints the batch again and records a second job.

GET /api/v1/templates

Lists the built-in paper sizes (by slug) and the shop's own templates (by id), with the label size in millimetres and the resolution the template was designed at. Archived templates are not listed and cannot be printed.

curl https://labelcraft.tech/api/v1/templates \
  -H "Authorization: Bearer YOUR_KEY"

{
  "templates": [
    {
      "id": "cmf1x9q2h0001",
      "name": "Shelf 62 x 29",
      "kind": "roll",
      "source": "custom",
      "labelWidthMm": 62,
      "labelHeightMm": 29,
      "dpi": 300,
      "version": 3
    },
    {
      "id": "dymo-30252",
      "name": "Dymo 30252 Address (3½ × 1⅛ in)",
      "kind": "roll",
      "source": "preset",
      "labelWidthMm": 88.89999999999999,
      "labelHeightMm": 28.575,
      "dpi": 203,
      "version": 1
    }
  ]
}

POST /api/v1/print

Renders one PDF for a template and a list of variants with quantities, records the job in the shop's print history (source API, with the key's name), and returns the bytes as base64 beside the warnings.

Variants are read live from the shop at print time: title, SKU, barcode, price, weight, metafields. You send ids and quantities, nothing else.

curl https://labelcraft.tech/api/v1/print \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "dymo-30252",
    "items": [
      { "variantId": 45678901234567, "qty": 2 },
      { "variantId": "gid://shopify/ProductVariant/45678901234568", "qty": 1 }
    ]
  }'

• template (string, required): a paper size slug or one of the shop's template ids, as listed by GET /templates.
• items (array, required): one entry per line, { variantId, qty }. variantId is a numeric id, a numeric string or a full gid; qty is a positive integer. The same variant may appear more than once.
• startPosition (integer, optional): for sheet templates, the index of the first label to use on the first sheet, from 0. Ignored on rolls.
• locale (en, fr, de or es, optional): the format of a printed date element and of prices on the label. Warning codes are stable and their messages are English; the app translates them by code on its own screens. Default en.

{
  "jobId": "cmf1xa77c0003",
  "filename": "labels-dymo-30252.pdf",
  "pageCount": 3,
  "labelCount": 3,
  "warnings": [
    {
      "code": "textOverflow",
      "labelIndex": 1,
      "element": "productTitle",
      "message": "Text overflows its box: \"Organic cotton crew neck, heavyweight, oversized fit\""
    }
  ],
  "pdfBase64": "JVBERi0xLjcK..."
}

• jobId: the print history row. It reprints from the app like any other job.
• pageCount and labelCount: what the PDF holds. labelCount is the sum of the quantities.
• warnings: never empty when something did not fit or a field came back empty. Same codes and sentences as the app. A print with warnings still returns the PDF; decide on your side whether to send it to the printer.
• pdfBase64: the PDF, base64. Decode it and hand it to your printer or your print server as is; it is already at the template's exact size.

curl https://labelcraft.tech/api/v1/templates/dymo-30252 \
  -H "Authorization: Bearer YOUR_KEY"

curl https://labelcraft.tech/api/v1/templates \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shelf 62 x 29",
    "layout": {
      "kind": "roll", "labelWidthMm": 62, "labelHeightMm": 29, "dpi": 300,
      "elements": [
        { "type": "productTitle", "xMm": 2, "yMm": 2, "widthMm": 58, "heightMm": 8, "fontSize": 9 },
        { "type": "barcode", "xMm": 2, "yMm": 11, "widthMm": 58, "heightMm": 16, "barcodeFormat": "ean13" }
      ]
    }
  }'

curl -X PATCH https://labelcraft.tech/api/v1/templates/cmf1x9q2h0001 \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shelf 62 x 29 (v2)" }'

curl -X DELETE https://labelcraft.tech/api/v1/templates/cmf1x9q2h0001 \
  -H "Authorization: Bearer YOUR_KEY"

curl https://labelcraft.tech/api/v1/barcodes/audit \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "values": ["4006381333931", "4006381333932", "SKU-0042"] }'

{
  "results": [
    { "value": "4006381333931", "status": "valid", "format": "GTIN-13", "message": "..." },
    { "value": "4006381333932", "status": "invalid", "suggestion": "4006381333931", "message": "..." },
    { "value": "SKU-0042", "status": "internal", "message": "..." }
  ]
}

Errors

Every error is a JSON object { error: { code, message } } with the extra fields named below. The message says what to change; the code is stable.

What the API shares with the app

The print endpoint calls the same functions the in-app print calls: the same variant read, the same money formatting, the same metafield resolution, the same brand kit rules for the plan, the same font and barcode floors before and after the merchant's own printer calibration, and the same render engine. A test in the code base fails if one of those calls is replaced by a copy or dropped.

What the API does not do: it never asks for a review, never pushes to PrintNode, never appends the calibration ruler, and never offers the in-app metafield fixes. Delivery to a printer is yours.

Coming next

Generating barcodes for products that have none (writing to the catalogue) is planned as a further slice. It is not available yet, and this page only documents what the code does today.

Questions, or a system you want to connect: support@labelcraft.tech.