---
name: zplcloud-api-print
description: Print ZPL labels through the zplCloud REST API (e.g. the GTIN-LABEL design). Use when the user wants to add ZPL label printing via api.zplcloud.com to an app, script or agent.
---

# zplCloud - ZPL label printing via API

Use this skill to render ZPL for a saved design and print it on a Zebra (or compatible)
printer through the zplCloud API.

## Base

- API domain: `https://api.zplcloud.com`
- OpenAPI/Scalar docs: `https://api.zplcloud.com/api/scalar`
- Auth: API key via header `X-API-Key: <KEY>` or HTTP Basic Auth `curl -u <KEY>:`
- API keys are created in the zplCloud platform (Account → API tab).

## Endpoints (v1)

- `GET /v1/fonts` - list available system fonts.
- `POST /v1/zpl/render/design/{designId}` - render a saved design to ZPL.

## Design ID

A design is addressed as `<name>.<id>` - the design tag (lowercase a-z, 0-9, `_`, `-`)
and its numeric ID, separated by a dot. Example: `gtin-label.42`.

## Render flow (example: GTIN-LABEL)

1. Save the design in the zplCloud designer. The save response/URL shows the design ID
   (`name.id`, e.g. `gtin-label.42`).
2. Send the data records as a JSON array of objects. Field names must match the
   design's variable placeholders.

```bash
curl -X POST "https://api.zplcloud.com/v1/zpl/render/design/gtin-label.42" \
  -H "X-API-Key: $ZPLCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"gtin":"4006381333930","produkt":"Demo","charge":"LOT-42"}]'
```

Response: `application/x-zpl` - one `^XA … ^XZ` block per record.

## Print the returned ZPL

Send the returned ZPL to a printer on TCP port 9100:

```python
import socket

def print_zpl(zpl: str, host: str, port: int = 9100):
    with socket.create_connection((host, port), timeout=10) as s:
        s.sendall(zpl.encode("utf-8"))
```

## Limits

- Max 500 records per request, body max 1 MB.
- The design must belong to the API key owner's email or company (scope check).

## Example (Python, complete)

```python
import requests

KEY = "<your-api-key>"
DESIGN = "gtin-label.42"

resp = requests.post(
    f"https://api.zplcloud.com/v1/zpl/render/design/{DESIGN}",
    headers={"X-API-Key": KEY, "Content-Type": "application/json"},
    json=[{"gtin": "4006381333930", "produkt": "Demo", "charge": "LOT-42"}],
)
resp.raise_for_status()
zpl = resp.text
print(zpl)
```