Templates

Generate PDF

Generate custom PDFs with text, barcodes (Code128), QR codes, DataMatrix codes, and lines using explicit x,y positioning. This endpoint is useful for creating shipping labels, asset tags, inventory bin labels, and other custom documents.

# Authentication

This endpoint requires authentication with an API key that has the templates:write scope.

# Performance

PDF generation runs in a dedicated background service, so rendering a complex document with many elements does not tie up the API. The generated PDF is uploaded to cloud storage and a public URL is returned.

# Request Body

# Page Sizes

Note: 72 points = 1 inch. Coordinates use top-left origin with Y increasing downward.

# Raster Density (DPI)

The generated PDF is a vector document, so text and lines are resolution-independent and always render crisply at any zoom or print size. The dpi parameter controls only the raster elements - barcodes, QR codes, DataMatrix codes, and images.

One rule covers all of them: dpi sets the rasterization density for everything the server rasterizes - barcodes, QR/DataMatrix codes, and SVG. For bitmaps you supply yourself, dpi only ever trims excess pixels, and only when you pass it explicitly, so your original image data is never altered unless you ask.

Note: Supplying dpi at all - even 216, the value used when it is omitted - opts supplied bitmaps into resampling. This differs from omitting dpi, which leaves them at their native resolution. If you want bitmaps untouched, omit dpi rather than sending 216. This distinction applies to bitmaps only: barcode/QR/matrix and SVG output is identical either way.

Higher DPI values produce crisper raster elements at the cost of a larger output file. For most on-screen use the default (216) is ideal; raise it toward 300-600 for thermal/laser label printing, or lower it toward 72-150 to minimize file size when print sharpness is not a concern.

        const data = {
  size: "4x6",
  orientation: "portrait",
  dpi: 300, // sharper barcodes for thermal label printing
  raw: [
    { type: "code128", x: 20, y: 20, value: "1Z999AA10123456784", height: 50, width: 248 },
    { type: "qr", x: 100, y: 90, value: "https://track.example.com/1Z999AA10123456784", height: 80 },
  ],
};

      

# Element Types

# Text Element

# Code128 Barcode

# QR Code

# DataMatrix Code

# Line

# Image

# Image Formats

PNG, JPEG, and SVG are supported. The format is detected from the data itself, so no extra field is needed.

SVG may be supplied in any of these forms:

Because a PDF cannot hold an SVG directly, SVG input is rasterized to a bitmap before embedding, at the element's on-page size scaled to dpi, so it stays crisp at print size - up to the raster ceiling below.

Sizing. An SVG is drawn into the element's width x height box. Omit height and it is derived from the SVG's own aspect ratio, so a logo sent with only a width keeps its proportions; omit both and the SVG's intrinsic size is used. A box larger than the page is scaled down to fit the page dimensions, preserving its aspect ratio. (x and y are not adjusted, so an SVG positioned near the edge can still overflow.)

Limits. Every limit below reports as a per-element entry in errors while the rest of the PDF still renders - no limit fails the whole request.

Repeating the same image is free. The usual case - one logo on every label of a sheet - is rasterized and embedded once and then reused, so it costs the budget once no matter how many elements draw it, and the output PDF carries a single copy of the bitmap. This applies to PNG and JPEG as well as SVG.

Distinct artwork per element is what consumes the budget, so page-sized SVGs are limited in number. Approximate ceilings for full-bleed artwork, one distinct document per element:

The raster ceiling can cap effective density below the dpi you request for page-sized SVG. A full-page A4 element at dpi: 600 would need 7016 pixels on its long edge; capped at 5000, it renders at roughly 433 effective dpi. Label-sized artwork is unaffected - a 4x6 label at dpi: 600 needs 3600 pixels and gets the full density.

SVG documents containing entity declarations (<!ENTITY>, or a <!DOCTYPE> with an internal subset) are rejected, because expanding them can consume unbounded CPU; a plain <!DOCTYPE svg PUBLIC ...> with no internal subset is fine.

# Font Families

Use mono for tracking numbers, SKUs, and other codes where character alignment matters.

# Text Alignment

Note: When using center or right alignment, the x coordinate becomes the anchor point for alignment rather than the text starting position.

# Example Request - Shipping Label

        const data = {
  size: "4x6",
  orientation: "portrait",
  raw: [
    {
      type: "text",
      x: 20,
      y: 20,
      value: "SHIP TO:",
      height: 10,
      font_family: "inter",
      font_weight: "bold"
    },
    {
      type: "text",
      x: 20,
      y: 35,
      value: "John Smith",
      height: 14,
      font_family: "inter",
      font_weight: "black"
    },
    {
      type: "text",
      x: 20,
      y: 52,
      value: "123 Main Street",
      height: 12,
      font_family: "inter"
    },
    {
      type: "text",
      x: 20,
      y: 67,
      value: "New York, NY 10001",
      height: 12,
      font_family: "inter"
    },
    {
      type: "line",
      x: 20,
      y: 90,
      height: 1,
      width: 248
    },
    {
      type: "text",
      x: 20,
      y: 110,
      value: "1Z999AA10123456784",
      height: 10,
      font_family: "mono"
    },
    {
      type: "code128",
      x: 20,
      y: 125,
      value: "1Z999AA10123456784",
      height: 50,
      width: 248
    },
    {
      type: "qr",
      x: 188,
      y: 200,
      value: "https://track.example.com/1Z999AA10123456784",
      height: 80
    }
  ]
};

const res = await fetch("https://api.packagex.io/v1/templates/pdf/generate", {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

const pdfUrl = res.data.url; // URL to the generated PDF
const filename = res.data.filename; // e.g., "pdf_abc123.pdf"

      

# Example Request - Asset Tag with Font Families

        const data = {
  size: "custom",
  width: 144,
  height: 72,
  orientation: "portrait",
  raw: [
    {
      type: "text",
      x: 5,
      y: 8,
      value: "ASSET TAG",
      height: 6,
      font_family: "inter",
      font_weight: "bold"
    },
    {
      type: "text",
      x: 5,
      y: 50,
      value: "AST-001234",
      height: 8,
      font_family: "mono"
    },
    {
      type: "code128",
      x: 5,
      y: 18,
      value: "AST-001234",
      height: 25,
      width: 100
    },
    {
      type: "matrix",
      x: 110,
      y: 18,
      value: "AST-001234",
      height: 30,
      width: 30
    }
  ]
};

const res = await fetch("https://api.packagex.io/v1/templates/pdf/generate", {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

      

# Response

        {
  "data": {
    "url": "https://storage.googleapis.com/bucket/org_123/pdf/pdf_abc123.pdf",
    "filename": "pdf_abc123.pdf"
  },
  "message": "PDF generated successfully"
}

      

# Partial Success Response

If some elements fail to render but the PDF is still generated:

        {
  "data": {
    "url": "https://storage.googleapis.com/bucket/org_123/pdf/pdf_abc123.pdf",
    "filename": "pdf_abc123.pdf",
    "errors": [
      {
        "index": 2,
        "type": "code128",
        "error": "Invalid barcode value"
      }
    ]
  },
  "message": "PDF generated with 4/5 elements rendered successfully"
}

      

# Error Responses

# Empty Raw Array (400)

        {
  "errors": [
    {
      "message": "Array must contain at least 1 element(s)",
      "path": ["body", "raw"]
    }
  ]
}

      

# Custom Size Missing Dimensions (400)

        {
  "errors": [
    {
      "message": "width and height are required when size is 'custom'"
    }
  ]
}

      

# Margins Exceed Page Height (400)

Returned when margin_top + margin_bottom is greater than or equal to the page height, leaving no printable area. margin_top and margin_bottom each default to 18pt (0.25 inch), so short custom pages fit by default; this error occurs when the supplied margins are too large for the page.

        {
  "status": 400,
  "message": "Top and bottom margins (margin_top 40 + margin_bottom 40 = 80pt) leave no printable area on a 72pt-tall page. margin_top and margin_bottom each default to 18pt when omitted - pass smaller margin_top and margin_bottom (e.g. 0) in the request to fit this page height."
}

      

# Invalid Color Format (400)

        {
  "errors": [
    {
      "message": "Invalid color format. Use hex code like #FF0000",
      "path": ["body", "raw", 0, "color"]
    }
  ]
}

      

# Invalid Font Family (400)

        {
  "errors": [
    {
      "message": "Invalid enum value. Expected 'inter' | 'mono'",
      "path": ["body", "raw", 0, "font_family"]
    }
  ]
}

      

# Too Many Elements (400)

        {
  "errors": [
    {
      "message": "Array must contain at most 500 element(s)",
      "path": ["body", "raw"]
    }
  ]
}

      

# Example Request - Inventory Bin Label

        const data = {
  size: "custom",
  width: 216,  // 3 inches
  height: 72,  // 1 inch
  orientation: "portrait",
  raw: [
    {
      type: "text",
      x: 10,
      y: 15,
      value: "BIN A-01-03",
      height: 14,
      font_family: "inter",
      font_weight: "black"
    },
    {
      type: "code128",
      x: 10,
      y: 35,
      value: "A-01-03",
      height: 25,
      width: 120
    },
    {
      type: "text",
      x: 140,
      y: 42,
      value: "A-01-03",
      height: 12,
      font_family: "mono"
    }
  ]
};

const res = await fetch("https://api.packagex.io/v1/templates/pdf/generate", {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

      

# Example Request - Text Alignment

        const data = {
  size: "A4",
  orientation: "portrait",
  raw: [
    // Left aligned (default) - text starts at x
    {
      type: "text",
      x: 50,
      y: 50,
      value: "Left Aligned",
      height: 18,
      font_family: "inter",
      align: "left"
    },
    // Center aligned - text centered at x (page center = 297.5)
    {
      type: "text",
      x: 297,
      y: 80,
      value: "Center Aligned",
      height: 18,
      font_family: "inter",
      font_weight: "bold",
      align: "center"
    },
    // Right aligned - text ends at x (right margin = 545)
    {
      type: "text",
      x: 545,
      y: 110,
      value: "Right Aligned",
      height: 18,
      font_family: "inter",
      align: "right"
    },
    // Horizontal line to show alignment
    {
      type: "line",
      x: 50,
      y: 130,
      height: 1,
      width: 495
    }
  ]
};

const res = await fetch("https://api.packagex.io/v1/templates/pdf/generate", {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

      

# Example Request - Rotated Label Elements

        const data = {
  size: "4x6",
  orientation: "landscape",
  raw: [
    {
      type: "text",
      x: 50,
      y: 100,
      value: "FRAGILE",
      height: 24,
      font_family: "inter",
      font_weight: "black",
      color: "#FF0000",
      angle: -15
    },
    {
      type: "line",
      x: 20,
      y: 150,
      height: 2,
      width: 200,
      color: "#FF0000"
    },
    {
      type: "text",
      x: 50,
      y: 180,
      value: "HANDLE WITH CARE",
      height: 16,
      font_family: "inter",
      font_weight: "bold"
    }
  ]
};

const res = await fetch("https://api.packagex.io/v1/templates/pdf/generate", {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

      

# Best Practices

# Coordinate System

• All coordinates are in points (72 points = 1 inch)
• The origin (0, 0) is at the top-left corner
• X increases to the right, Y increases downward
• Elements are positioned by their top-left corner

# Element Ordering

Elements are rendered in the order they appear in the raw array. Later elements will appear on top of earlier ones if they overlap.

# Font Selection

• Use inter (default) for general text - it has excellent readability at all sizes
• Use mono (Fira Mono) for tracking numbers, SKUs, and codes where character alignment is important

# Barcode Best Practices

• Ensure barcode values contain only valid characters for the barcode type
• Code128 supports alphanumeric characters
• QR codes can encode URLs, text, or binary data
• DataMatrix codes are ideal for small spaces with high data density

# Performance Tips

• Keep the number of elements under 100 for optimal performance
• Use the smallest appropriate page size for your use case
• Pre-validate barcode values before sending to avoid partial success responses