API reference

GET /api/v1/printers

Lists the printers of the PrintNode account connected to the shop in LabelCraft (Settings, Send labels straight to a printer), so a print can go to one of them: printerId on POST /print. online says whether LabelCraft would send to it right now (the printer online in PrintNode and its computer connected); selectedInApp marks the printer the app's own Send to printer uses.

A shop without PrintNode connected answers 409 printnode_not_connected. A key PrintNode refuses, or PrintNode out of reach, answers 502 printnode_error with stage, kind and retryable. The PrintNode key is only ever sent to PrintNode, never back in an answer.

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

{
  "printers": [
    {
      "id": 73065,
      "name": "Zebra ZD421",
      "state": "online",
      "computerName": "Front desk PC",
      "computerState": "connected",
      "online": true,
      "selectedInApp": true
    },
    {
      "id": 73071,
      "name": "Rollo X1040",
      "state": "offline",
      "computerName": "Warehouse PC",
      "computerState": "connected",
      "online": false,
      "selectedInApp": false
    },
    {
      "id": 73066,
      "name": "Zebra GK420d",
      "state": "online",
      "computerName": "Warehouse PC",
      "computerState": "connected",
      "online": true,
      "selectedInApp": false
    }
  ]
}

GET /api/v1/templates/:id

One template with its full layout: a built-in paper size by slug or one of the shop's non-archived templates by id. The layout is the exact object the editor stores, so a system can read a paper size, change a few fields and POST the result under its own name.

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

POST /api/v1/templates

Creates a template from { name, layout } and answers 201 with the same shape as GET /templates/:id. The layout goes through the editor's own rules: unknown fields are dropped, fields that only make sense on some element types are removed from the others, a logo or a custom font must decode, and an element outside the label is refused with 422 and the box that would fit.

A template created here appears in the app's template list and prints from the app and from POST /print alike.

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" }
      ]
    }
  }'

• name (string, required): 1 to 80 characters.
• layout.kind (roll or sheet), layout.labelWidthMm and layout.labelHeightMm (mm, above 0), layout.dpi (integer, default 203).
• layout.sheet (required on a sheet): pageWidthMm, pageHeightMm, marginTopMm, marginLeftMm, gutterXMm, gutterYMm, columns, rows.
• layout.rollAcross (optional, true): a thermal roll with two or more labels side by side, such as the zebra-2-375x1-2across paper size. Send it with layout.kind sheet and a layout.sheet that is one row of the roll: pageWidthMm the roll's width, pageHeightMm the row's height (the label's height on die-cut stock), rows 1, columns 2 or more. Each page of the PDF that POST /print returns is one row of the roll, and startPosition is ignored, as on any roll; in the app, a Zebra (ZPL) file prints each row as one format as wide as the roll, unless layout.printBandMm leaves part of the label out (below). Refused with invalid_request on a roll layout, with any value other than true, with rows other than 1, with fewer than 2 columns, when the left margin, the labels and the gaps are wider than pageWidthMm, or when the top margin and the label are taller than pageHeightMm.
• layout.printBandMm (optional, with layout.rollAcross only): { fromMm, toMm }, the part of every label of the row that the print head reaches, in mm from the label's left edge. A head narrower than the roll leaves the outer edges of the roll unprinted: on zebra-2-375x1-2across, laid out for a 56 mm head, it is { fromMm: 2.1625, toMm: 28 }. Each linear barcode then keeps its bars and its outer digits inside it whenever they fit there without going under a scanning minimum (bar width, 2 printer dots a bar, digit and bar height), the rest of its box counting as quiet zone; otherwise it is placed in its box as without the band. A barcode drawn past it anyway says so in warnings (barcodeOutsidePrintBand), and so does any other element whose ink runs past it, on each label (elementOutsidePrintBand): the lines of a text, or its whole box under a background colour, a line's stroke, an image's rectangle. In the app, a row whose band leaves part of the label out gets no Zebra (ZPL) file for now: print the PDF; a band of the whole label limits nothing. Refused with invalid_request without layout.rollAcross, or unless 0 <= fromMm < toMm <= layout.labelWidthMm.
• layout.panels (optional, on a roll only): { cutsMm: [...] }, where a slit, a fold or a perforation running along the roll cuts one label into panels, 1 to 8 positions in mm from the label's left edge, in increasing order, each panel at least 1 mm wide. A barcode then counts only the white of its own panel as its quiet zone, and an element whose box runs over a cut comes back as an elementAcrossPanelCut warning.
• layout.calibration (optional): offsetXMm and offsetYMm, within 5 mm of 0.
• layout.elements (1 to 60): each with type, xMm, yMm, widthMm, heightMm, and the optional fields of that type (fontSize, bold, align, overflow, value, color, barcodeFormat, qrSource, includeText, serial, imageData and imageSource for a logo, moneyFormat for price and compareAtPrice, strikethrough for compareAtPrice, optionNames for variantTitle, rotation for a text, a logo or a photo). imageSource "product" draws each label's product photo from Shopify in that logo's box instead of imageData, on PDF prints only; a label whose photo cannot be had prints without it and says why in warnings. moneyFormat takes Shopify's money format grammar, for example "{{amount_with_comma_separator}} €", and is kept on price and compareAtPrice only and dropped from other types; leave it out and the label prints the shop's own format. strikethrough true draws a line through a compareAtPrice on PDF prints, only on a label whose compare-at price is above its price; it is dropped from other types, false is stored as absent, and a ZPL print shows the amount without the line. A format the label cannot print (an unknown placeholder, no placeholder at all, more than 80 characters once HTML tags are removed, or no decimals on a currency that has cents) is refused with invalid_request, one detail line per element at fault. optionNames turns a variantTitle element into the value of ONE option of the variant, named as in Shopify and matched without regard to case: ["Größe", "Rahmengröße", "Size"] prints the first of those options the variant has, so "56" rather than "Red / 56". It holds 1 to 5 names of 1 to 255 characters without control characters, is kept on variantTitle only and dropped from other types; a list that is empty once each name is trimmed is refused with invalid_request. A variant without any of the names prints nothing there and says why in warnings (code variantOptionMissing, or variantOptionLoadFailed when the options could not be read). rotation turns a text element, a logo or a photo clockwise inside its box, which keeps its position and size: 0, 90, 180 or 270, and 0 is stored as absent. A barcode, a QR code or a line does not turn: a rotation other than 0 on one is refused with invalid_request, and so is any other value, one detail line per element at fault. GET a built-in paper size to see a complete example of every type you need.

PATCH /api/v1/templates/:id

Changes the name, the layout or both. Every change bumps the version and stores an immutable snapshot, so a job printed before the change reprints with the same layout. Built-in paper sizes answer 409 template_read_only: GET the paper size, POST it under your name, then edit that one.

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)" }'

DELETE /api/v1/templates/:id

Archives the template: it leaves the list and can no longer print, and answers 204. Nothing is erased, so past jobs keep reprinting from their snapshots. Built-in paper sizes answer 409.

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

POST /api/v1/barcodes/audit

Runs the app's barcode check over a list of values, the same check behind the Barcode check page and the pre-print warnings. Nothing is read from the shop and nothing is written: send the codes your system holds and get, for each, whether it is a valid retail GTIN, missing, invalid (with the corrected value when only the check digit is wrong), a restricted prefix (in-store, coupon, ISBN) or an internal Code 128 value. An 8-digit value the app reads as a UPC-E (starting with 0, outside the 0000 block GS1 leaves empty) gets no corrected value: it may be the UPC-E of a UPC-A, which upcA names.

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

• values (array of strings, required): 1 to 500 values of at most 64 characters.

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

• status: valid, missing, invalid, restricted or internal. suggestion appears only when a corrected value exists. prefix names the GS1 range when it is known. upcA appears when the value may be a UPC-E: the 12-digit UPC-A it stands for.