Does gPdf create carrier labels for me?

No. Your carrier or shipping system creates the carrier shipment and barcode payload. gPdf renders that data into a PDF label.

Can I use Template Render for shipping labels?

Yes. Use JSON Render while designing or testing the label, then use Template Render when the layout is stable and callers should only send data.

Does gPdf output ZPL?

No. The public render APIs output PDF. If your print path needs ZPL, convert or route the PDF outside gPdf.

What should I validate before production?

Print on the real printer and label stock, scan the barcode with production scanners, and confirm the carrier-specific text and payloads come from your shipping system.

Logistics and labels

Shipping label API for 4x6 PDF labels

Generate print-ready 4x6 shipping label PDFs from order JSON with vector barcodes, label page sizes, and deterministic warehouse reprints.

PRIMARY API JSON Render

ENDPOINT /api/v1/pdf/render

SYSTEMS WMS / OMS / 3PL backend / shipping backend

Try in Playground → Read the docs

Job to be done

Render label-sized PDFs from order, recipient, service, and tracking data so a warehouse or ecommerce backend can print the same 4x6 label reliably during fulfillment and reprint it deterministically when needed.

When to use this API

Your system already has the tracking number, destination, service text, and barcode payload.
You need PDF output for Zebra, SATO, Honeywell, or other thermal-printer workflows.
You want vector barcode modules instead of raster barcode images pasted into a PDF.
You need the same payload to render the same label for reprints and audit evidence.

What it does not replace

You need to buy postage, rate a shipment, or create a carrier label through a carrier account.
You need a ZPL replacement endpoint. gPdf returns PDF, not printer command language.
You need carrier certification from gPdf. Scanner and carrier acceptance testing remains yours.

Which endpoint to call

PRIMARY

/api/v1/pdf/render

JSON Render is the default path for this workflow.

SECONDARY 1

/api/v1/template-render

Use this when the workflow needs the related API path, template contract, or capabilities lookup.

Minimal request

POST /api/v1/pdf/render - minimal 4x6 label with a tracking barcode.

{
  "pages": [
    {
      "size": "label_4_6_in",
      "elements": [
        {
          "type": "text",
          "x": 4,
          "y": 6,
          "content": "SHIP TO",
          "style": { "font_size": 8, "font_family": "NotoSans-Regular" }
        },
        {
          "type": "text",
          "x": 4,
          "y": 13,
          "content": "Acme Warehouse\n1200 Logistics Pkwy\nMemphis TN 38116",
          "style": { "font_size": 11, "font_family": "NotoSans-Regular" }
        },
        {
          "type": "barcode",
          "format": "code128",
          "content": "1Z999AA10123456784",
          "x": 4,
          "y": 62,
          "width": 92,
          "height": 22,
          "barcode_text": { "enabled": true, "position": "bottom" }
        }
      ]
    }
  ]
}

What gPdf handles

Label-sized PDF pages such as 4x6 inch workflows.
Vector barcode rendering for carrier and warehouse label content.
Text, address blocks, service marks, lines, boxes, and optional template binding.
Deterministic PDF output for warehouse reprints.

What your system owns

Carrier account, postage purchase, service selection, and tracking number creation.
Correct barcode payloads, human-readable text, addresses, and routing data.
Printer setup, label stock, scan testing, and carrier acceptance checks.

Production checklist

Print test labels on the real printer model and label stock.
Verify barcode scan rates at the target DPI and scanner distance.
Store source shipment data or the returned PDF according to your reprint policy.
Use Template Render once the label layout is approved and reused across systems.
Keep carrier-specific logic outside the rendering request.

Claim boundaries

gPdf renders the label PDF; it does not buy postage or talk directly to carriers.
gPdf is not a carrier-label certification authority.
The API is PDF output, not ZPL, EPL, or another thermal-printer command stream.

The shipping label API shape

Shipping label pages are not a separate carrier endpoint. You call JSON Render with a label-sized page, text blocks, lines, optional images, and barcode elements. For repeated labels, publish the approved layout as a template and call Template Render with shipment data.

This keeps ownership clear. gPdf owns PDF rendering and barcode drawing. Your system owns the carrier transaction, shipment state, and payload semantics.

JSON Render versus Template Render

Use JSON Render when your fulfillment system generates the full layout or when the operations team is still tuning coordinates. Use Template Render when the warehouse has approved a stable label layout and every caller should send the same data fields.

Either path returns PDF output. The difference is whether the caller describes the layout on every request or references a published template_id.

Print testing matters

Thermal label quality is physical. Validate the output on real label stock, real printers, and real scanners. Barcode payload correctness, quiet zones, printer darkness, and carrier-specific rules are production responsibilities outside the rendering API.

FAQ

Does gPdf create carrier labels for me?: No. Your carrier or shipping system creates the carrier shipment and barcode payload. gPdf renders that data into a PDF label.
Can I use Template Render for shipping labels?: Yes. Use JSON Render while designing or testing the label, then use Template Render when the layout is stable and callers should only send data.
Does gPdf output ZPL?: No. The public render APIs output PDF. If your print path needs ZPL, convert or route the PDF outside gPdf.
What should I validate before production?: Print on the real printer and label stock, scan the barcode with production scanners, and confirm the carrier-specific text and payloads come from your shipping system.