Print Imports (printer)

Alpha

The contract may change without notice, and imports created with it are not guaranteed to remain compatible. Not covered by the deprecation policy.

Plan requirement

Available from the Suite plan — the same entitlement that gates generating the corresponding assets.

type: "printer" imports produce single-page print PDF designs. The flow is identical to static imports — Create → Upload Assets → Validate → Poll Status — but the payload is authored in a fundamentally different space: physical units, pt font sizes, and CMYK colors.

This page lists every rule that differs from static imports. Everything not mentioned here behaves exactly as documented on Create Import.

Multi-page print

printer covers single-page PDFs only. For multi-page print documents, use type: "printer_multipage" — the same printer rules on this page, but the print setup (unit, width, height, bleed_size, safe_size, dpi) is declared once at the top level because every page shares one size, and an ordered pages[] array carries only each page's background_color and layers.

Physical units

The design declares a required top-level unit — "mm" or "in" — and every geometric value in the design is a float in that unit:

• Format width / height
• Layer layout (x, y, width, height)
• Geometric properties: stroke.width, radius corners, padding sides, star_dimension, star_margin, background_radius / background_offset_x / background_offset_y, and the side_border lengths
• bleed_size / safe_size

Font sizes are the exception: font_size and min_font_size are floats in pt (points), allowed range 0.48 – 240. Omitting font_size still means auto-size, exactly as on static.

One unit governs the whole design: unit is declared once at the top level and is required there. A format carrying its own unit is rejected with unknown_field.

Render DPI (optional)

Each printer format may declare an optional dpi — an integer, per format — that sets the render resolution:

• Range: 10 – 300, and additionally capped by a per-format ceiling that shrinks for very large (OOH) formats so the rendered output stays within the platform's pixel budget:

  dpi ≤ min(300, floor(72 · √(225 000 000 / (w_pt · h_pt))))

  where w_pt / h_pt are the format's width / height converted to points (mm → pt: mm / 25.4 · 72; in → pt: in · 72). A dpi above this ceiling → out_of_range at formats[i].dpi.

• Omitted → the backend uses that ceiling as the format's default DPI (small and mid-size formats therefore default to 300).

dpi is printer-only — supplying it on a static or animated format is rejected with unsupported_for_type. It is also surfaced read-only on GET /designs/{uuid} and GET /designs/{uuid}/formats/{format}, and it round-trips through GET /designs/{uuid}/as-import.

Printer-only format fields

Field	Type	Required	Description
dpi	integer	No	Render resolution for this format. 10 – 300, capped by the area-based ceiling above; over the ceiling → out_of_range. Omitted → the ceiling is used as the default. See Render DPI.
bleed_size	float ≥ 0	No	Bleed size in the format's unit. Presence enables bleed on the created design.
safe_size	float ≥ 0	No	Safe-zone size in the format's unit. Presence enables the safe zone.

Supplying any of these three fields on a static import is rejected with unsupported_for_type at formats[i].<field>.

The two sizes work as concentric offsets around the trim (the format's width × height):

Bleed — background art runs to here

Trim — the final cut size

Safe zone — keep text & logos inside

Artwork is authored at trim size; bleed_size extends the background outward, safe_size insets a margin for critical content.

Colors: CMYK

Every color field on a printer design — including format background_color, nested stroke.color, text background_color / text_decoration_color, and qrcode colors — is stored as a CMYK token:

cmyk(C,M,Y,K)        cmyka(C,M,Y,K)        cmyka(C,M,Y,K,A)

• Components are integers 0–100. No % signs. Case-insensitive.
• Whitespace around components is accepted — cmyk(0, 100, 90, 10) is valid and is normalised to the canonical cmyk(0,100,90,10) before the design is stored.
• cmyka(...) with 4 components is valid — the alpha component is optional.

You do not have to author in CMYK. A solid hex value on a printer import is accepted and converted to CMYK for you, and you get a color_converted warning naming the path and both values. The conversion works in the other direction too: a CMYK token on a static / animated import is converted to hex (uppercase, #RRGGBB / #RRGGBBAA). Alpha survives either way — #RRGGBBAA ⇄ cmyka(C,M,Y,K,A).

Color value	On printer	On static
#RRGGBB / #RRGGBBAA	Converted to cmyk(...) + color_converted warning	Accepted
cmyk(...) / cmyka(...)	Stored as sent	Converted to hex + color_converted warning
linear-gradient(...)	Rejected — unsupported_for_type	Accepted (on 8 fields)

Conversion is approximate — author CMYK when the exact ink matters

The conversion uses no ICC profile, so the CMYK it produces is a close approximation of your hex value, not a colour-managed match. If a specific press colour matters, send cmyk(...) yourself: it is stored exactly as you sent it, nothing is converted, and no warning is emitted.

Gradients on print are rejected, not converted — they are a supported feature on static and animated only. See Colors & Gradients for the grammar and the fields that accept one.

Why a gradient is fatal where a solid colour is not

Converting a gradient means collapsing it to its first colour: the design would come back a flat fill and the import would report success. Converting a solid colour only costs some accuracy, and the warning tells you it happened.

CMYK token grammar

Components are bare integers 0–100 with no % sign — cmyk(0,100,90,10) or, equivalently, the spaced form cmyk(0, 100, 90, 10) (whitespace is accepted and normalised away). A % sign or a component outside 0–100 is rejected with invalid_payload. Tokens are case-insensitive.

The one field never touched: inline markup inside a text payload stays hex even on printer; payload content is never inspected, converted or rejected.

Printer color defaults are CMYK, too: text, shape, button, and qrcode colors default to cmyk(0,0,0,100) (black), and the button text color to cmyk(0,0,0,0) (white).

Size limits

Schema-level validation on printer geometry only enforces sign constraints (floats ≥ 0, width/height > 0). On top of that, the format size and each layer's layout are checked against the platform's pixel limits converted at 300 DPI — a violation fails the POST with out_of_range at the offending path, and the message includes the computed pixel value so you can size down accordingly:

Value	Pixel bounds (at 300 DPI)
Format width / height	1 – 20 000
Layout x / y	−19 999 – 19 999
Layout width / height	1 – 19 999
bleed_size / safe_size	≥ 0 only (no upper bound)
Every other geometric property (stroke.width, radius corners, gap, star_dimension, star_margin, side_border.thickness / .padding / .spread, background_radius)	≥ 0 only (no upper bound)
Signed geometric properties (padding sides, background_offset_x / _y, side_border.offset, mask center_x / center_y)	unconstrained (may be negative, no upper bound)

Only the format box and the layer box are capped. Individual geometric properties carry no upper bound on print.

The numbers behind the cap

20 000 px at 300 DPI ≈ 1 693 mm ≈ 66.7 in — physical dimensions beyond that are rejected. The 300 DPI here is only the validation and text-layout bridge; the actual render DPI is the per-format dpi or its computed default.

Individual properties are uncapped because a pixel cap is meaningless once you author in millimetres — a 1 000 px cap is 84.7 mm, which says nothing about an A1 poster.

"default" layout/properties entries (and flat values shared across formats) are checked against every declared unit; per-format entries against their own format's unit.

Properties print cannot render

You can send a static design straight to a print import without hand-stripping anything first.

Property	On	What happens
shadow	all layer types	Dropped, import succeeds
text_shadow	button	Dropped, import succeeds
pattern_name, pattern_color	shape	Dropped, import succeeds
overlay	image	Dropped as a whole object, one warning
Gradient colour tokens	any colour field	Rejected with unsupported_for_type

Each drop emits a property_dropped_for_type warning naming the layer path and the property, one per occurrence — read them back from GET .../import/json/{id}.

Dropped properties are still fully validated before removal: a malformed shadow object, or a gradient in pattern_color, is still invalid_payload. shadow is validated against the static definition — integer blur / offset_x / offset_y in pixels, not your format's unit.

Why dropping is the default and a gradient is the exception

A property is only fatal when the result would silently be artwork you did not author, rather than less of the artwork you did. None of the dropped effects reach paper, so removing one leaves exactly what you sent minus an effect you are told about by name. A gradient is different: print collapses it to its first stop, so accepting it would hand back a flat fill where you asked for a blend.

Images: originals are stored untouched

Print image handling is built around one rule: what you upload is exactly what prints.

• The original file is stored byte-for-byte — embedded ICC profile and file format preserved — and is what the PDF renderer consumes at generation time. No recompression, no color-space conversion.
• TIFF is accepted as a layer src on printer (data-URI mimetype and .tif / .tiff filenames or URLs). On static, TIFF is rejected with unsupported_for_type.
• TIFF files and files over 20 MB automatically get a lightweight display proxy so the design stays responsive in the editor — the untouched original is still used when generating.
• Accepted input formats: JPEG, PNG, WebP, TIFF, GIF, SVG.

Asset size limits

Asset	static	printer
Layer asset — filename src (presigned upload)	20 MB	500 MB
Layer asset — data: URI (decoded size)	2 MB	2 MB

A data: URI src is capped at 2 MB decoded on every design type and every layer type, because it travels inside the JSON request body. The presigned upload flow supports the full per-type cap since files go directly to storage.

Above any cap, host the file and reference it by public https:// URL — URL sources have no size cap and are fetched server-side, with no upload step.

Request example

A complete A4 flyer (210 × 297 mm) with bleed and safe zone, a headline in pt/CMYK, and a TIFF hero image:

{
  "name": "A4 Flyer",
  "type": "printer",
  "unit": "mm",
  "target": { "kind": "design", "project_uuid": "f0a9d2bc-1c1a-4f0e-9d4d-c7b8c2c8a7e1" },
  "formats": [
    {
      "name": "a4-flyer",
      "width": 210,
      "height": 297,
      "bleed_size": 3,
      "safe_size": 5,
      "background_color": "cmyk(0,0,0,0)"
    }
  ],
  "layers": [
    {
      "name": "headline",
      "type": "text",
      "layout": { "x": 20, "y": 25, "width": 170, "height": 35 },
      "properties": {
        "payload": "Grand Opening — This Weekend",
        "color": "cmyk(0,100,90,10)",
        "font_size": 42,
        "min_font_size": 24,
        "text_align": "center"
      }
    },
    {
      "name": "hero",
      "type": "image",
      "layout": { "x": 20, "y": 75, "width": 170, "height": 150 },
      "properties": {
        "src": "hero.tif",
        "fitting_type": "cover",
        "alignment": "middle center"
      }
    },
    {
      "name": "footer-bar",
      "type": "shape",
      "layout": { "x": 0, "y": 265, "width": 210, "height": 32 },
      "properties": {
        "shape": "rectangle",
        "background_color": "cmyk(100,60,0,40)"
      }
    }
  ]
}

All layout values are mm floats; font_size: 42 and min_font_size: 24 are pt; every color is a CMYK token. The hero.tif filename yields one uploads[] entry with max_bytes: 500000000.

Reading print settings back

Once the import is DONE:

• GET /designs/{uuid} and GET /designs/{uuid}/formats/{format} return dpi (read-only integer), plus bleed_size / safe_size (floats in the format's unit, present only when enabled) on each printer format.
• GET /designs/{uuid}/as-import round-trips printer designs in the same physical-unit space — mm/in geometry, pt font sizes, CMYK colors, and bleed_size / safe_size included. See Export a Design for printer round-trip semantics.

Related

• Create Import — request/response reference shared by both design types
• Import Status — error and warning code reference
• Export a Design — export an existing printer design as an import payload