Options and paper sizes

Options tune how a PDF prints. Every option is optional: anything you omit is filled from the printer’s defaults in the dashboard, and options the printer does not support are ignored and listed as warnings in the job’s stateMessage.

{ "options": { "copies": 2, "paper": "A4", "duplex": "long-edge", "color": false, "pages": "1-3,5" } }

Option	Values	What it does
`copies`	integer, 1 to 999	Number of copies of each page range
`paper`	a name from the printer’s `papers` or `customPapers`	Paper size, for example `A4` or `Letter`
`duplex`	`long-edge`, `short-edge`, `one-sided`	Two-sided printing. `long-edge` flips on the long side (portrait books), `short-edge` on the short side (calendars)
`color`	`true` or `false`	`false` prints in grayscale
`dpi`	text such as `600x600`	Print resolution, from the printer’s `dpis`
`bin`	a name from the printer’s `bins`	Paper tray or output bin
`media`	a name from the printer’s `medias`	Media type, for example `Plain` or `Photo`
`collate`	`true` or `false`	Keep multiple copies in page order
`fit_to_page`	`true` or `false`	Scale the page to fit the paper
`rotate`	`0`, `90`, `180`, `270`	Rotate the page in degrees
`pages`	text such as `1-3,5`	Pages to print, as numbers and ranges separated by commas
`nup`	integer, 1 to 16	Pages per sheet, from the printer’s `nup`

Unknown option names are rejected with 400 invalid_request. Raw jobs ignore options (see Raw printing). If an option has a value the printer cannot honour, the job still prints and stateMessage explains what was dropped, for example duplex ignored: printer cannot print two-sided. Read stateMessage on the finished job if the output differs from what you asked for.

Reading capabilities

GET /v1/printers/{id} returns what the printer supports in capabilities. The agent reads it from the operating system, so it reflects the installed driver.

{
  "id": "PRINTER_ID",
  "name": "Test A4 Laser",
  "capabilities": {
    "papers": { "A4": [2100, 2970], "Letter": [2159, 2794], "80mm Receipt": [800, null] },
    "bins": ["Tray 1", "Tray 2"],
    "dpis": ["600x600"],
    "duplex": true,
    "color": false,
    "collate": true,
    "copies": 99,
    "extent": [[900, 1480], [2970, 4200]],
    "medias": ["Plain"],
    "nup": [1, 2, 4],
    "printrate": { "unit": "ppm", "rate": 30 },
    "supports_custom_paper_size": false
  },
  "defaultOptions": { "paper": "A4", "duplex": "long-edge" },
  "customPapers": []
}

papers maps each paper name to [width, height] in tenths of a millimetre, so "A4": [2100, 2970] is 210 by 297 mm. bins, dpis and medias list the values you can pass to bin, dpi and media. A paper dimension can be null when the driver does not report it, as for a roll of receipt paper ("80mm Receipt": [800, null], 80 mm wide with no fixed length). extent is [[minWidth, minHeight], [maxWidth, maxHeight]] in the same unit and gives the range of custom paper sizes the printer accepts, or null. printrate is the printer’s rated speed, for example 30 pages per minute, or null. duplex, color and collate say whether the printer supports them, copies is the largest copy count it accepts, and nup lists the pages per sheet it offers.

Printer defaults and custom paper sizes

Set defaults once and send only what differs per job. In the dashboard, open the printer and edit its defaults. Over the API, use PATCH /v1/printers/{id} with the admin scope:

curl -X PATCH https://api.printeasy.adfinite.com/v1/printers/PRINTER_ID \
  -H "Authorization: Bearer $PRINTEASY_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "defaultOptions": { "paper": "A4", "duplex": "long-edge", "color": false },
    "customPapers": [{ "name": "Label 100x150", "width": 1000, "height": 1500 }]
  }'

customPapers adds paper sizes the printer does not list, such as label stock. width and height use the same unit as papers, tenths of a millimetre, so the example above is 100 by 150 mm. Once saved, pass the name as paper. A printer accepts up to 50 custom papers. Sending customPapers replaces the whole list. PATCH /v1/printers/{id} also sets displayName, enabled (the live switch) and remarks.

Platform notes

nup works on macOS and Linux only.
On Windows, PDFs print through SumatraPDF. pages, copies, fit_to_page, rotate (90 and 270), color, duplex, paper and bin are honoured. dpi, media, collate, nup and rotate 180 are ignored, so a job that asks for rotate 180 prints without rotation. Each ignored option adds a warning to stateMessage.
dpi, media and collate apply on macOS and Linux.
Paper names come from the operating system and the driver. Read papers before you hard-code a name.

Get started

Printing

Build

SDKs

Migrate

Options and paper sizes

Reading capabilities

Printer defaults and custom paper sizes

Platform notes

​Reading capabilities

​Printer defaults and custom paper sizes

​Platform notes

Reading capabilities

Printer defaults and custom paper sizes

Platform notes