Create a print job

Send an uploaded CloudPrint document to a selected printer with idempotency and explicit print options.

POST/api/v1/print-jobsAPI version: v1operationId: createPrintJobView as Markdown

What this endpoint does

Send an uploaded CloudPrint document to a selected printer with idempotency and explicit print options.

Authentication

Send a short-lived access token in Authorization: Bearer <access_token>.

Required scopes: print_jobs:write

Request

Production base URL: https://public-api.cloudprint.me/api/v1/print-jobs

Parameters

Name	Location	Type	Required	Description	Constraints
`Idempotency-Key`	header	`string`	no	Optional key that prevents duplicate print jobs for the same account and payload.	maxLength: 128

Request body

Content type: application/json

Name	Type	Required	Description	Constraints
`document_id`	`string (uuid)`	yes	Stable UUID returned after a successful document upload.	—
`printer_id`	`string (uuid)`	yes	Stable CloudPrint UUID of the destination printer.	—
`copies`	`integer`	no	Number of copies CloudPrint asks the printer to produce.	min: 1; max: 99; example: `1`
`intent`	`string`	no	Business purpose of the print job, used for diagnostics and sensible defaults.	enum: `document`, `shipping_label`, `product_label`, `invoice`, `packing_slip`, `a4_document`, `receipt`; example: `"shipping_label"`
`color_mode`	`string`	no	Requested color handling; `default` leaves the decision to the printer configuration.	enum: `default`, `monochrome`, `color`; example: `"default"`
`duplex_mode`	`string`	no	Requested one-sided or two-sided printing mode.	enum: `default`, `simplex`, `duplex_long_edge`, `duplex_short_edge`; example: `"default"`
`media_width_mm`	`number \| null`	no	Requested media or label width in millimetres.	min: 1; max: 2000; example: `58`
`media_height_mm`	`number \| null`	no	Requested media or label height in millimetres.	min: 1; max: 2000; example: `40`
`dpi`	`integer \| null`	no	Target print resolution in dots per inch; use a value supported by the printer.	min: 72; max: 2400; example: `203`
`scale_mode`	`string`	no	Controls whether the document keeps its size or is fitted to the target media.	enum: `none`, `fit`; example: `"none"`
`orientation`	`string`	no	Requested page orientation; `default` uses printer settings.	enum: `default`, `portrait`, `landscape`; example: `"default"`
`offset_x_mm`	`number`	no	Horizontal print offset in millimetres.	min: -2000; max: 2000; example: `0`
`offset_y_mm`	`number`	no	Vertical print offset in millimetres.	min: -2000; max: 2000; example: `0`
`margin_top_mm`	`number`	no	Additional print margin in millimetres.	min: 0; max: 2000; example: `0`
`margin_right_mm`	`number`	no	Additional print margin in millimetres.	min: 0; max: 2000; example: `0`
`margin_bottom_mm`	`number`	no	Additional print margin in millimetres.	min: 0; max: 2000; example: `0`
`margin_left_mm`	`number`	no	Additional print margin in millimetres.	min: 0; max: 2000; example: `0`

Example requests

cURL

bash

curl -sS https://public-api.cloudprint.me/api/v1/print-jobs \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-100045-label' \
  -d '{
    "document_id": "44444444-4444-4444-8444-444444444444",
    "printer_id": "11111111-1111-4111-8111-111111111111",
    "copies": 1,
    "intent": "shipping_label",
    "media_width_mm": 58,
    "media_height_mm": 40,
    "dpi": 203
  }'

PHP

php

<?php

$payload = json_encode([
    'document_id' => '44444444-4444-4444-8444-444444444444',
    'printer_id' => '11111111-1111-4111-8111-111111111111',
    'copies' => 1,
    'intent' => 'shipping_label',
    'media_width_mm' => 58,
    'media_height_mm' => 40,
    'dpi' => 203,
], JSON_THROW_ON_ERROR);

$response = file_get_contents('https://public-api.cloudprint.me/api/v1/print-jobs', false, stream_context_create([
    'http' => [
        'method' => 'POST',
        'header' => [
            'Authorization: Bearer ' . getenv('CLOUDPRINT_ACCESS_TOKEN'),
            'Content-Type: application/json',
            'Idempotency-Key: order-100045-label',
        ],
        'content' => $payload,
    ],
]));

$printJob = json_decode((string) $response, true, flags: JSON_THROW_ON_ERROR);

Response

HTTP status: 201 — Print job created

Response fields

Name	Type	Required	Description	Constraints
`print_job_id`	`string (uuid)`	yes	Stable UUID of the print job; persist it for status checks and support.	—
`document_id`	`string (uuid)`	yes	Stable UUID returned after a successful document upload.	—
`document_mime_type`	`string`	yes	MIME type of the supplied document.	example: `"application/pdf"`
`document_format`	`string`	yes	Explicit print format, such as `pdf` or `raw`.	enum: `pdf`, `raw`; example: `"pdf"`
`document_raw_language`	`string \| null`	yes	Printer command language used by RAW data, for example ZPL or EPL.	enum: `tspl`, `zpl`, `cpcl`, `escpos`; example: `null`
`printer_id`	`string (uuid)`	yes	Stable CloudPrint UUID of the destination printer.	—
`status`	`string`	yes	Current resource or workflow state; use the endpoint-specific enum values.	enum: `pending`, `reserved`, `printing`, `printed`, `failed`, `cancelled`; example: `"pending"`
`copies`	`integer`	yes	Number of copies CloudPrint asks the printer to produce.	min: 1; max: 99; example: `1`
`intent`	`string`	yes	Business purpose of the print job, used for diagnostics and sensible defaults.	enum: `document`, `shipping_label`, `product_label`, `invoice`, `packing_slip`, `a4_document`, `receipt`; example: `"shipping_label"`
`color_mode`	`string`	yes	Requested color handling; `default` leaves the decision to the printer configuration.	enum: `default`, `monochrome`, `color`; example: `"default"`
`duplex_mode`	`string`	yes	Requested one-sided or two-sided printing mode.	enum: `default`, `simplex`, `duplex_long_edge`, `duplex_short_edge`; example: `"default"`
`media_width_mm`	`number \| null`	yes	Requested media or label width in millimetres.	min: 1; max: 2000; example: `58`
`media_height_mm`	`number \| null`	yes	Requested media or label height in millimetres.	min: 1; max: 2000; example: `40`
`dpi`	`integer \| null`	yes	Target print resolution in dots per inch; use a value supported by the printer.	min: 72; max: 2400; example: `203`
`scale_mode`	`string`	yes	Controls whether the document keeps its size or is fitted to the target media.	enum: `none`, `fit`; example: `"none"`
`orientation`	`string`	yes	Requested page orientation; `default` uses printer settings.	enum: `default`, `portrait`, `landscape`; example: `"default"`
`offset_x_mm`	`number`	yes	Horizontal print offset in millimetres.	min: -2000; max: 2000; example: `0`
`offset_y_mm`	`number`	yes	Vertical print offset in millimetres.	min: -2000; max: 2000; example: `0`
`margin_top_mm`	`number`	yes	Additional print margin in millimetres.	min: 0; max: 2000; example: `0`
`margin_right_mm`	`number`	yes	Additional print margin in millimetres.	min: 0; max: 2000; example: `0`
`margin_bottom_mm`	`number`	yes	Additional print margin in millimetres.	min: 0; max: 2000; example: `0`
`margin_left_mm`	`number`	yes	Additional print margin in millimetres.	min: 0; max: 2000; example: `0`
`created_at`	`string (date-time)`	yes	ISO 8601 timestamp recorded by CloudPrint.	—
`reserved_at`	`string \| null (date-time)`	yes	ISO 8601 timestamp recorded by CloudPrint.	—
`started_at`	`string \| null (date-time)`	yes	ISO 8601 timestamp recorded by CloudPrint.	—
`completed_at`	`string \| null (date-time)`	yes	ISO 8601 timestamp recorded by CloudPrint.	—
`failure_reason`	`string \| null`	yes	Machine-readable or diagnostic reason recorded when printing fails.	—

Example response

json

{
  "print_job_id": "11111111-1111-4111-8111-111111111111",
  "document_id": "11111111-1111-4111-8111-111111111111",
  "document_mime_type": "application/pdf",
  "document_format": "pdf",
  "document_raw_language": null,
  "printer_id": "11111111-1111-4111-8111-111111111111",
  "status": "pending",
  "copies": 1,
  "intent": "shipping_label",
  "color_mode": "default",
  "duplex_mode": "default",
  "media_width_mm": 58,
  "media_height_mm": 40,
  "dpi": 203,
  "scale_mode": "none",
  "orientation": "default",
  "offset_x_mm": 0,
  "offset_y_mm": 0,
  "margin_top_mm": 0,
  "margin_right_mm": 0,
  "margin_bottom_mm": 0,
  "margin_left_mm": 0,
  "created_at": "2026-08-06T12:00:00Z",
  "reserved_at": null,
  "started_at": null,
  "completed_at": null,
  "failure_reason": null
}

Errors

HTTP status	Description
`401`	OAuth bearer token is missing or invalid
`403`	OAuth bearer token lacks documents:write or print_jobs:write
`409`	Idempotency key conflict or unsupported print route. Unsupported routes include details.reason.
`422`	Print job validation failed
`429`	Rate limit exceeded
`500`	Unexpected error

Integration guidance

Send a stable Idempotency-Key for every request that may be retried.
A 201 response means the job exists, not that paper has been printed. Poll the returned job until printed or failed.
Validate requested options against the selected printer capabilities.

Upload a document for printingUpload a print-ready PDF or explicit RAW printer-language payload before creating a CloudPrint print job.Get a print job statusRead one CloudPrint print job until it reaches the terminal printed or failed status.Idempotent print-job creationPrevent duplicate physical prints when retrying CloudPrint print-job requests after a timeout or network failure.

Create a print job ​

What this endpoint does ​

Authentication ​

Request ​

Parameters ​

Request body ​

Example requests ​

cURL ​

PHP ​

Response ​

Response fields ​

Example response ​

Errors ​

Integration guidance ​

Related documentation ​