---
title: "Create a print job"
description: "Send an uploaded CloudPrint document to a selected printer with idempotency and explicit print options."
---
<nav class="docs-breadcrumb" aria-label="Breadcrumb"><a href="/docs/">CloudPrint Documentation</a><span aria-hidden="true">/</span><span>API reference</span></nav>

# Create a print job

<p class="docs-lead">Send an uploaded CloudPrint document to a selected printer with idempotency and explicit print options.</p>

<div class="api-endpoint-summary"><span class="api-method api-method-post">POST</span><code>/api/v1/print-jobs</code><span><strong>API version:</strong> v1</span><span><strong>operationId:</strong> <code>createPrintJob</code></span><a href="/docs/api/v1/print-jobs/create/index.md">View as Markdown</a></div>

## 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.

## Related documentation

<div class="docs-card-grid"><a class="docs-card" href="/docs/api/v1/documents/upload/"><strong>Upload a document for printing</strong><span>Upload a print-ready PDF or explicit RAW printer-language payload before creating a CloudPrint print job.</span></a>
<a class="docs-card" href="/docs/api/v1/print-jobs/get/"><strong>Get a print job status</strong><span>Read one CloudPrint print job until it reaches the terminal printed or failed status.</span></a>
<a class="docs-card" href="/docs/api/v1/idempotency/"><strong>Idempotent print-job creation</strong><span>Prevent duplicate physical prints when retrying CloudPrint print-job requests after a timeout or network failure.</span></a></div>

<nav class="docs-resource-links" aria-label="Next steps"><a href="/docs/api/v1/explorer/">OpenAPI</a><a href="https://my.cloudprint.me">Open account</a><a href="/docs/legal/privacy/">Privacy Policy</a><a href="/docs/legal/terms/">Terms</a><a href="/docs/legal/payments-and-refunds/">Payment and refunds</a><a href="/docs/legal/data-processing/">DPA</a></nav>