The Stripe for Printing

Four rules that decide whether your integration works

Printing is physical and asynchronous. These four cover almost every integration that looks correct in testing and misbehaves in production — worth reading whether you are writing the code yourself or having an AI agent write it.

1. 201 Created does not mean “printed”. The response comes back as soon as the job is queued; the label is rendered and printed afterwards by the customer’s own device. Render and hardware errors therefore never appear in the create response — only in the job. Poll GET /v1/print/jobs/{id} every ~2 s until status is completed, failed or cancelled. A job you never poll is a failure you will never see.

2. A retry needs a new idempotency key. X-Idempotency-Key caches the response for 24 h, so replaying a key returns the original job and prints nothing — that is what protects you from double labels on a network retry. The trap: after a job comes back failed, reusing the same key returns that failed job instead of reprinting, so a naive retry loop leaves the row permanently unprinted. Put an attempt counter in the key: erp:<order>-<line>:<attempt>.

3. Check the printer before you send. A job aimed at an offline printer sits in queued indefinitely. Call GET /v1/fleet/printers first: the target needs is_online: true and cloud_print_enabled: true — the latter is switched on by the customer in the desktop app and cannot be enabled through the API.

4. Ask the design what fields it wants. Do not guess variable names. GET /v1/designs/{id}/variables returns the exact keys plus a ready-made example_payload. Unknown keys in data are ignored silently, which looks exactly like a binding bug.

Many labels at once: data accepts an array of rows (max 1000) — one row renders one label, which is how serial numbers and per-row values work. copies repeats the whole job instead. Use the array for different labels, copies for N identical ones.

Mirroring an ERP or database: keep the “printed” state in a table you own rather than writing into the source system’s own schema — that is what breaks ERP vendor support contracts. Match on a stable row key and reuse that key in the idempotency header above.

The same guidance is machine-readable in the OpenAPI spec, so an agent that reads the spec gets it without being told.

Authentication — two ways in

API key (Bearer) — the default for code. Send Authorization: Bearer sk_live_xxx on every request. This is what all four official SDKs use.

OAuth 2.0 — for no-code connectors (Make, Zapier) so your users never copy a key by hand. Authorization-code flow with optional S256 PKCE; client_credentials is also accepted with the API key passed as client_secret.

• GET  /v1/oauth/authorize
• POST /v1/oauth/token
• GET  /.well-known/oauth-authorization-server

The issued access_token is a long-lived LabelInn API key, so expires_in and refresh_token are deliberately omitted (RFC 6749 §5.1) — treat the token as non-expiring rather than attempting a refresh.

Scopes — what a key is allowed to do

Every key carries a scope list, chosen when you create it in Settings → API Keys and editable afterwards without rotating the secret. A scope is either a bare resource or resource:action:

• designs       every action on designs
• designs:read  view only — GET
• designs:write create and edit — POST/PUT/PATCH (implies read)
• designs:delete delete only — DELETE

The action is derived from the HTTP method, so “may read designs but never create one” works on every endpoint. Resources: print, fleet, designs, webhooks, usage, connect, audit, workflows, rules, sites, analytics, render.

Scope an agent key tightly. A key you hand to an AI agent or a third-party integration should rarely carry print — the Design only preset gives full authoring with no ability to put ink on media. A key that cannot print is not shown printing tools over MCP at all, so the agent never plans around a capability it does not have.

A request outside a key's scopes returns 403 INSUFFICIENT_PERMISSIONS with a required_scope field naming exactly the scope that would allow it. Keys created before scopes were split by action hold bare resource scopes and are unaffected.

You can also set a per-key rate ceiling in requests per minute, at or below your plan's limit — useful for capping what a single integration can do.