---
title: "Render GS1-128 / UCC-128 carton shipping labels as PDF or ZPL (shared by all marketplace apps)."
method: POST
path: "/v1/labels"
tags: ["Labels"]
---

# Render GS1-128 / UCC-128 carton shipping labels as PDF or ZPL (shared by all marketplace apps).

`POST /v1/labels`

## Request

- Base URL: `https://signaledi.com/api`
- URL: `https://signaledi.com/api/v1/labels`
- Auth: HTTP bearer

Platform-wide label renderer for GitHub, Vercel, AWS Marketplace, RapidAPI, and generic API clients authenticated with a `platform`-scoped key (or dashboard session). Also gated by `SHIPPING_LABELS_ENABLED` (404 when off). Optional `asnContent` enforces SSCC ↔ 856 MAN consistency (422 on mismatch). Does not send EDI. Shopify Admin uses the same engine via `/api/shopify/embedded/labels`. Letterhead/BrandProfile is never applied to label zones.

## Request body

- LabelsRequest
  - `orderId` string: Caller order reference (any non-empty id without spaces). Shopify GIDs are accepted when well-formed.
  - `poNumber` string: Purchase-order number (required when orderId is omitted).
  - `format` 'pdf' | 'zpl'
  - `templateId` string: Label template id (default gs1-128-4x6).
  - `shipFrom` object
    - `company` string
    - `lines` string[]
  - `shipTo` object
    - `company` string
    - `lines` string[]
  - `cartons` object[], required
    - `sscc` string: SSCC-18 (optional; generated when omitted).
    - `lines` object[]
      - `sku` string
      - `quantity` integer
  - `asnContent` string: Optional raw X12 856. When present, every label SSCC must appear as a MAN*GM value or the API returns 422.

## Response `200`

Label bytes (PDF or ZPL).

## Other responses

- `400`: Request body failed validation (`code` e.g. VALIDATION_ERROR, NO_WORKSPACE, BATCH_TOO_LARGE).
- `401`: Missing or invalid API key (`code` AUTH_UNAUTHORIZED).
- `403`: API key lacks the required `platform` scope (`code` PLATFORM_SCOPE_REQUIRED), its lane is invalid (API_KEY_ENVIRONMENT_INVALID), the workspace is not entitled to the platform API (PLATFORM_NOT_ENTITLED), or a supplied `workspaceId` does not match the authenticated workspace (FORBIDDEN).
- `404`: Resource not found, or the /v1 platform is disabled (`code` NOT_FOUND / PARTNER_NOT_FOUND / WORKSPACE_NOT_FOUND).
- `422`: SSCC on labels does not match MAN segments in asnContent (`code` SSCC_ASN_MISMATCH).
- `429`: Rate limit exceeded (`code` RATE_LIMITED).
- `500`: Unexpected server error (`code` e.g. PARSE_FAILED, VALIDATE_FAILED, OUTBOUND_FAILED, INBOUND_FAILED, BATCH_FAILED, TRANSACTIONS_FAILED, DOCUMENT_RECEIPT_FAILED, DOCUMENT_PAYLOAD_FAILED). Sanitized bodies carry an opaque `correlationId` to quote to support; internal error text is never echoed.

---

[API](https://skmtc.dev/signaledi/apis/signaledi-developer-api.md) · [All operations](https://skmtc.dev/signaledi/apis/signaledi-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signaledi/apis/signaledi-developer-api/revisions/9bc596644a10?raw)