Multi-Page Print Imports (printer_multipage)

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_multipage" imports produce multi-page print PDF designs — one PDF with ordered pages. Single-page print PDFs stay on type: "printer".

The model is one print document with an ordered list of pages. Every printer authoring rule — physical units, pt font sizes, CMYK colors, unsupported properties, untouched image originals, asset caps — applies exactly as documented on Print Imports. This page covers only what is different: the payload shape.

The flow is identical to every other import — Create → Upload Assets → Validate → Poll Status.

One document size, declared once

All pages in a multi-page design have the same dimensions. That is a product rule, not a limitation of the payload format — so the print setup (unit, width, height, and optionally bleed_size, safe_size, dpi) lives at the top level of the payload and is declared exactly once. A pages[i] object carries only what genuinely varies page to page: its background_color and its layers.

Payload shape

A multi-page payload replaces formats + top-level layers with top-level print setup plus an ordered pages array.

{
  "name": "Product Brochure",
  "type": "printer_multipage",
  "unit": "mm",
  "width": 210,
  "height": 297,
  "bleed_size": 3,
  "safe_size": 5,
  "dpi": 300,
  "pages": [
    { "background_color": "cmyk(0,0,0,0)", "layers": [ ] }
  ]
}

Top-level print setup

Field	Type	Required	Description
unit	enum	Yes	"mm" or "in" (lowercase — the enum is case-sensitive). The physical authoring unit for every geometric value in the whole document.
width	float > 0	Yes	Page width in unit. Applies to every page. Checked against the pixel-equivalence ceiling (20 000 px at 300 DPI) — violations report at width.
height	float > 0	Yes	Page height in unit. Same rule, reported at height.
bleed_size	float ≥ 0	No	Bleed in unit. Presence enables bleed for the document — 0 counts as enabled; omitting the field is the only way to disable it.
safe_size	float ≥ 0	No	Safe-zone size in unit. Same presence-means-enabled rule.
dpi	integer	No	Render resolution for the document. 10 – 300, capped by the area-based ceiling. See Render DPI.
pages	array (1 – 30)	Yes	Ordered pages — array order is page order. A count outside 1 – 30 → out_of_range at pages. A single-page document should use type: "printer", though 1 page is accepted.

formats and layers are not used on printer_multipage — supplying either is unknown_field. Array order is the printed page order — the first entry is page_1, the second page_2, and so on:

1page_1

→

2page_2

→

3page_3

…

Page object

A pages[i] entry accepts exactly two fields — nothing else:

Field	Type	Required	Description
background_color	color	Yes	A CMYK token (cmyk(...) / cmyka(...)). A cover legitimately differs from an inside page, so this is per page. A solid hex is accepted and converted to CMYK for you (with a color_converted warning); a linear-gradient(...) → unsupported_for_type at pages[i].background_color.
layers	array (1 – 80)	Yes	Printer layers for this page, authored in the document's unit. A page is single-format, so layout and properties are normally plain flat objects; a "default" key is also accepted (any other key → unknown_format_key). An empty array → out_of_range with expected: { "min": 1, "max": 80 }.

Anything else on a page is unknown_field

A page must not carry unit, width, height, bleed_size, safe_size, dpi, or name — every one of those is unknown_field at pages[i].<field>. Page names are assigned automatically (page_1 … page_N). The shape deliberately makes non-uniform pages unrepresentable, so there is no equality check to trip over: if you need pages of different sizes, they are different documents.

No shared layers

There are no cross-page shared layers. Every layer belongs to exactly one page; to place an element on every page, include it in each page's layers. There is also no z_position field — layer order within a page's array determines stacking.

Render DPI (optional)

dpi is a single top-level integer for the whole document:

• Range: 10 – 300, additionally capped by an area-based ceiling that shrinks for very large documents so the rendered output stays inside the platform's pixel budget:

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

  where w_pt / h_pt are the top-level width / height converted to points (mm → pt: mm / 25.4 · 72; in → pt: in · 72). Because the document has one size, there is one ceiling — no per-page arithmetic. A dpi above it → out_of_range at dpi, with both expected.max and received populated.

• Omitted → the backend uses that same ceiling as the document's default DPI. A4-sized and smaller documents therefore default to 300.

The resolved value is surfaced read-only on design reads and round-trips as one top-level dpi through GET /designs/{uuid}/as-import.

Everything else is printer rules

Each page's layers reuse the Print Imports contract in full:

• CMYK colors — every color field is stored as a cmyk() / cmyka() token (integers 0 – 100). A solid hex color is accepted and converted for you, with a color_converted warning; a linear-gradient(...) color is still unsupported_for_type. See Create Import → Colors.
• Physical units — all geometry is floats in the document's unit; font_size / min_font_size are floats in pt (0.48 – 240).
• Image originals stored untouched — byte-for-byte, ICC profile and format preserved; TIFF accepted; a lightweight display proxy is generated for TIFF / files over 20 MB. See Print Imports → Images.
• Properties print cannot render — shadow, text_shadow, pattern_name, pattern_color and overlay_* are all accepted and dropped with a property_dropped_for_type warning. Gradient colours remain fatal. See Print Imports.
• Pixel-equivalence size limits — geometry is checked against the platform's pixel limits at 300 DPI (ceiling 20 000 px). See Print Imports → Size limits.

Error paths follow the payload shape: document-level problems report at width, height, bleed_size, safe_size, unit or dpi; page-level problems carry the page index, e.g. pages[1].background_color, pages[1].layers[3].properties.color.

Multi-page specifics

• Layer names must be unique within a page, but may repeat across pages — each page is validated independently.
• Group layer_ids are page-scoped. A group may only reference layers on its own page; a cross-page reference is conditional_dependency_missing at pages[i].layers[j].layer_ids[k] (layer_ids sits on the layer, not inside properties).
• uploads[] is keyed by (page, layer). The same filename on N layers yields N upload entries, N storage keys and N stored copies — there is no filename-level deduplication, because layer names may legitimately repeat across pages. If several pages share one asset, reference it by public https:// URL instead: no upload entry, no duplicate storage.

Asset size limits

Identical to printer:

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

Request example

A two-page A4 brochure — a cover and an inside page. The print setup is declared once; each page brings only its background and its layers:

{
  "name": "Product Brochure",
  "type": "printer_multipage",
  "target": { "kind": "design", "project_uuid": "f0a9d2bc-1c1a-4f0e-9d4d-c7b8c2c8a7e1" },
  "unit": "mm",
  "width": 210,
  "height": 297,
  "bleed_size": 3,
  "safe_size": 5,
  "dpi": 300,
  "pages": [
    {
      "background_color": "cmyk(80,20,0,0)",
      "layers": [
        {
          "name": "cover-title",
          "type": "text",
          "layout": { "x": 20, "y": 120, "width": 170, "height": 40 },
          "properties": {
            "payload": "2026 Collection",
            "color": "cmyk(0,0,0,0)",
            "font_size": 48,
            "text_align": "center"
          }
        }
      ]
    },
    {
      "background_color": "cmyk(0,0,0,0)",
      "layers": [
        {
          "name": "body",
          "type": "text",
          "layout": { "x": 20, "y": 30, "width": 170, "height": 230 },
          "properties": {
            "payload": "Everything you need for the season ahead.",
            "color": "cmyk(0,0,0,100)",
            "font_size": 18,
            "min_font_size": 12
          }
        },
        {
          "name": "photo",
          "type": "image",
          "layout": { "x": 20, "y": 150, "width": 170, "height": 120 },
          "properties": { "src": "hero.tif", "fitting_type": "cover", "alignment": "middle center" }
        }
      ]
    }
  ]
}

The two pages render in array order (page_1, then page_2). All layout values are mm floats, font sizes are pt, and every color is a CMYK token. hero.tif yields one uploads[] entry carrying "page": "page_2".

Reading a multi-page design back

Once the import is DONE:

• GET /designs/{uuid} returns a pages[] array (not formats) plus elements_per_page, an object keyed page_1 … page_N. See Design Details → multi-page designs.
• GET /designs/{uuid}/as-import round-trips multi-page designs back into this exact shape — top-level print setup, per-page background and layers.

Related

• Print Imports — the single-page printer rules every page inherits
• Create Import — request/response reference shared by every design type
• Import Status — error and warning code reference
• Export a Design — export an existing multi-page design as an import payload