Twoje etykiety. Twoje dane. Jedno API.

From a saved design to useful output.

1. Save a personal label. Add placeholders such as {sku} and {price}. For API-time variables, review the editor’s fidelity warnings and save as Vector ZPL.
2. Create a key in Dashboard → API & Integrations. API access needs active Pro entitlement, including Team membership or an admin grant. Choose Render only for this example; Full label API is needed to list, read or build print jobs. Copy the key when it is shown: it is displayed once.
3. Set your server environment. Copy the exact API base URL and the saved label’s UUID from your account. Set ZPLCRAFT_BASE_URL, ZPLCRAFT_API_KEY and LABEL_ID, then run an example below.

# Set ZPLCRAFT_BASE_URL, ZPLCRAFT_API_KEY and LABEL_ID
# in your server's environment. Copy the base URL from the dashboard.
curl --fail-with-body \
  "$ZPLCRAFT_BASE_URL/labels/$LABEL_ID/render" \
  -H "x-api-key: $ZPLCRAFT_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"variables":{"sku":"A-77","price":"9.99"},"format":"zpl"}' \
  --output label.zpl

Download the small JavaScript or Python client in Clients & n8n before running its example. Keep keys on your server; do not ship them in browser or mobile apps.

Base URL & authentication

https://<project>.supabase.co/functions/v1/label-api

Five operations. Explicit scopes.

Full label API keys receive labels:list, labels:read, render and print. Render-only and historical keys receive only render. Revoking a key prevents further access.

{
  "data": [{
    "id": "6f3d79d2-18f0-445f-b1d7-706988ecaf22",
    "name": "Shelf label", "width": 80, "height": 50,
    "dpi": 203, "revision": 4, "output_format": "vector",
    "created_at": "2026-08-01T10:00:00.000Z",
    "updated_at": "2026-08-12T08:30:00.000Z"
  }],
  "pagination": {
    "limit": 50, "offset": 0, "total": 1, "next_offset": null
  }
}

{
  "variables": { "sku": "A-77", "price": "9.99" },
  "format": "zpl"
}

{
  "records": [
    { "sku": "A-77", "price": "9.99" },
    { "sku": "A-78", "price": "12.50" }
  ],
  "copies": 2
}

One design, changing values.

{name} matches the corresponding variable case-insensitively. Send string values; keys are trimmed and must be safe, nonempty names. The server also converts other JSON values to strings (null becomes empty text). Saved field transforms run before token substitution.

Time uses the server clock (UTC in the hosted API). Format tokens: YYYY/YY, MM, DD, HH, mm and ss. COUNTER uses its seed; it does not advance across API records or copies. Supply your own serial number variable when each label needs a distinct value.

• Text: unmatched placeholders stay unchanged. Inserted values are ZPL hex-escaped; values cannot inject commands. Variable names containing underscores work with raw and saved ^FH-escaped spellings.
• Barcodes: missing variables or invalid digits, length, check digit or character set return 422 with field-level details. Native barcodes are substituted in place; marked raster barcodes (such as QR/Data Matrix/PDF417) are re-encoded. A larger payload can grow the symbol from its saved top-left corner.
• Older raster barcodes: re-save the design to add re-encoding metadata. Without it, older rasters retain their original values.

Plan around the shared budget.

The account and each key have a 60-unit, one-minute budget. Every authenticated attempt costs 1 unit. A valid print job costs 5 + record count units total: one record costs 6; 25 records cost 30. Copies do not add rate units. Rotating a key does not reset the account budget.

For 429 or 503, wait the Retry-After number of seconds before retrying. The supplied clients do not retry automatically. Do not reuse automatic retries from a byte-generation call to infer whether a physical print succeeded.

Errors you can act on.

Errors return JSON with an error message. Scope failures may include required_scope; transform and output-mode failures include code; barcode failures include fields.

{
  "error": "Variable substitution produced invalid barcode content.",
  "fields": [{
    "symbology": "EAN13", "template": "{sku}",
    "value": "A-77", "reason": "EAN-13 needs 12 or 13 digits"
  }]
}

Start with a small, readable client.

Download these source files into your server project. They cover listing, reading, stored ZPL, rendering and print-job generation. Both preserve status, scope and barcode errors, expose Retry-After, set a 30-second timeout by default and refuse HTTP redirects. HTTPS is required except for localhost development.

n8n: render a saved label

Import the workflow JSON using n8n’s Import from File action. It contains a manual trigger, an HTTP Request node and setup notes, with no embedded credential.

1. Replace the example project URL and REPLACE_WITH_LABEL_UUID in the HTTP Request node.
2. Create a Header Auth credential with header name x-api-key and your key as its value. Select this credential in the node. A render-only key is sufficient.
3. Use a saved Vector ZPL label containing {sku} and {price}, or edit the example variables to match your label.
4. Execute manually. Download the binary output named label as label.zpl. The workflow stops on HTTP errors; it does not retry or dispatch to a printer.

Credential setup: n8n HTTP Request documentation.