Cloud Printing

Print Jobs

Print jobs represent documents queued for printing. When you create a print job, the system automatically routes it to the best available printer based on document requirements and queue length.

Endpoints

Method	Endpoint	Description
GET	`/v1/cloud-printing/jobs`	List all print jobs
POST	`/v1/cloud-printing/jobs`	Create a new print job
GET	`/v1/cloud-printing/jobs/:job_id`	Retrieve a print job
POST	`/v1/cloud-printing/jobs/:job_id`	Update a print job status

Required Scopes

print_jobs:read - For listing and retrieving jobs
print_jobs:write - For creating and updating jobs

Create Print Job

        POST /v1/cloud-printing/jobs

Creates a new print job. The system will route the job to the most suitable printer based on capabilities and queue length.

Request Body

        {
  "location_id": "loc_abc123",
  "print_station_id": "prnt_stn_xyz",
  "printer_name": "HP LaserJet Pro",
  "data": "https://example.com/document.pdf",
  "name": "Invoice #12345",
  "resource": {
    "type": "shipment",
    "id": "shp_abc123",
    "document": "shipping_label"
  },
  "configuration": {
    "copies": 1,
    "color_print": false,
    "double_sided": true,
    "orientation": "portrait",
    "paper_size": "page_size_letter",
    "print_all_pages": true,
    "scaling": 1.0
  }
}

Parameters

Parameter	Type	Required	Description
location_id	string	✓	Location ID
data	string	✓	Document URL or base64 encoded data
print_station_id	string		Target station (auto-selects if omitted)
printer_name	string		Target printer name within station
name	string		Job name (max 191 chars)
resource	object		Link to a resource
configuration	object		Print settings

Document Data Formats

The data field accepts two formats:

URL:

        "data": "https://example.com/document.pdf"

Base64 with data URI:

        "data": "data:application/pdf;base64,JVBERi0xLjQK..."

Resource Types

Link print jobs to PackageX resources for tracking:

        // Shipment (shipping labels)
{
  "type": "shipment",
  "id": "shp_abc123",
  "document": "shipping_label"
}

// Fulfillment (packing slips)
{
  "type": "fulfillment",
  "id": "ful_abc123",
  "document": "packing_slip"
}

// Item (item labels)
{
  "type": "item",
  "id": "item_abc123",
  "document": "item_label"
}

// Asset (asset labels)
{
  "type": "asset",
  "id": "ast_abc123",
  "document": "asset_label"
}

// Manifest
{
  "type": "manifest",
  "id": "mnfst_abc123",
  "document": "manifest_document"
}

Configuration Options

Parameter	Type	Default	Description
copies	integer	1	Number of copies
color_print	boolean	false	Print in color
double_sided	boolean	false	Duplex printing
orientation	string	"portrait"	`portrait` or `landscape`
paper_size	string		Paper size value (see Models). Use `page_size_custom` to print at the printer's configured size, bypassing capability matching - this requires `print_station_id` and `printer_name`.
print_all_pages	boolean	true	Print all pages
pages_to_print	array		Specific pages (e.g., `["1", "3", "5-10"]`)
custom_dimensions	object		`{ width, height }` in inches. Only used when `paper_size` is `page_size_custom`; ignored otherwise. Both values must be positive and <= 1000.
scaling	number	1.0	Scale factor, 0.25-3.0 (e.g. `0.5` = 50%, `1.5` = 150%). Defaults to `1.0` (100%) when `configuration` is provided.
total_pages	integer		Override page count

Paper size is not always auto-detected. The API infers the paper size from the document's dimensions for common standard and label sizes, but it cannot resolve every size - transposed duplicates (e.g. 6x4 vs 4x6) and the decimal/large label sizes are not inferred. If the size cannot be determined and configuration.paper_size is not supplied, the request is rejected with a print_job.paper_size_required error. Pass configuration.paper_size explicitly whenever the document size may be ambiguous (e.g. PDFs generated from external sources). See Models for the full list of supported values.

Auto-Selection Logic

When print_station_id is not provided, the system automatically selects the best printer:

Filter by Capability - Only printers supporting the required paper size and orientation
Check User Access - Only stations the user can access
Match Location - Only stations at the specified location
Optimize Queue - Select the printer with the fewest queued jobs

Auto-selection does not apply when paper_size is page_size_custom. In that case you must specify both print_station_id and printer_name; the system skips all capability matching and routes the job directly to that printer.

If paper_size is omitted, the system tries to infer it from the document. When it cannot determine a size, the request fails with 400 - code print_job.paper_size_required and message Could not determine the paper size. Please specify configuration.paper_size. Pass paper_size explicitly to avoid this.

Label sizes are not auto-detected. The 34 label paper sizes (e.g. page_size_label_4x6, page_size_label_2_25x4) are never inferred from the document - you must always pass configuration.paper_size explicitly when printing to a label printer. Omitting it will result in a 400 print_job.paper_size_required error if the system cannot determine the size from the document dimensions alone. See Paper Size Values for the full list.

Custom Paper Size Example

Use page_size_custom to delegate sizing to the printer (for example, a label printer with a fixed roll size). Both print_station_id and printer_name are required:

        {
  "location_id": "loc_abc123",
  "print_station_id": "prnt_stn_xyz",
  "printer_name": "HP LaserJet Pro",
  "data": "https://example.com/document.pdf",
  "configuration": {
    "paper_size": "page_size_custom",
    "custom_dimensions": { "width": 4, "height": 6 }
  }
}

If either print_station_id or printer_name is missing, the request fails with 400 - print_station_id and printer_name are required for custom paper size.

custom_dimensions (inches) is optional - when omitted the printer uses its configured size. It is only honored with page_size_custom; sending it with any other paper size is ignored.

Minimal Request Example

        {
  "location_id": "loc_abc123",
  "data": "https://example.com/document.pdf"
}

Response

        {
  "data": {
    "object": "print_job",
    "id": "prnt_job_abc123",
    "name": "Invoice #12345",
    "status": "queued",
    "data_url": "https://storage.packagex.io/...",
    "station": {
      "id": "prnt_stn_xyz",
      "name": "Station-001",
      "display_name": "Front Desk Printer"
    },
    "printer": {
      "id": "019b1234-...",
      "name": "HP LaserJet Pro",
      "model": "HP LaserJet Pro M404dn"
    },
    "options": {
      "paper_size": "page_size_letter",
      "copies": 1,
      "orientation": "portrait",
      ...
    },
    "created_at": "2024-01-15T10:30:00.000Z"
  },
  "status": 201,
  "message": "Print job created"
}

Update Print Job Status

        POST /v1/cloud-printing/jobs/:job_id

Updates the status of a print job. This endpoint is typically used by the print station application to report job progress.

Status Transitions

        queued → processing → completed
                   → failed (requires reason)
                   → unreported (optional reason)
       → canceled

Request Examples

Mark as Processing:

        {
  "status": "processing"
}

Mark as Completed:

        {
  "status": "completed"
}

Mark as Failed:

        {
  "status": "failed",
  "reason": "Printer out of paper"
}

The reason field is required when status is failed and must be 3-1023 characters.

Mark as Unreported:

        {
  "status": "unreported",
  "reason": "Lost connection to the printer"
}

Use unreported when the station cannot determine the job's outcome. The reason is optional (3-1023 characters); when omitted it defaults to "Printer did not report the job outcome".

Cancel Job:

        {
  "status": "canceled"
}

Response

        {
  "data": {
    "object": "print_job",
    "id": "prnt_job_abc123",
    "status": "completed",
    ...
  },
  "message": "Print job updated"
}

List Print Jobs

        GET /v1/cloud-printing/jobs

Returns a paginated list of print jobs.

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Results per page (default: 20, max: 100)
order_by	string	Sort field: `created_at`, `updated_at`
direction	string	Sort direction: `asc`, `desc`
location_id	string	Filter by location ID
status	string	Filter by status
print_station_id	string	Filter by print station ID
printer	string	Filter by printer name
created_at[gte]	string	Filter by creation date
created_at[lte]	string	Filter by creation date
updated_at[gte]	string	Filter by update date
updated_at[lte]	string	Filter by update date

Example Request

        curl -H "PX-API-KEY: your_api_key" \
     "https://api.packagex.io/v1/cloud-printing/jobs?status=queued&print_station_id=prnt_stn_abc123"

Response

        {
  "data": [
    {
      "object": "print_job",
      "id": "prnt_job_abc123",
      "name": "Invoice #12345",
      "status": "queued",
      "station": {...},
      "printer": {...},
      ...
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "has_more": true
  },
  "message": "5 print jobs retrieved"
}

Retrieve Print Job

        GET /v1/cloud-printing/jobs/:job_id

Retrieves a single print job by ID.

Example Request

        curl -H "PX-API-KEY: your_api_key" \
     "https://api.packagex.io/v1/cloud-printing/jobs/prnt_job_abc123"

Response

        {
  "data": {
    "object": "print_job",
    "id": "prnt_job_abc123",
    "name": "Invoice #12345",
    "status": "completed",
    "reason": null,
    "data_url": "https://storage.packagex.io/...",
    "data_type": "application/pdf",
    "resource_id": "shp_abc123",
    "resource_document": "shipping_label",
    "station": {
      "id": "prnt_stn_xyz",
      "name": "Station-001",
      "display_name": "Front Desk Printer"
    },
    "printer": {
      "id": "019b1234-...",
      "name": "HP LaserJet Pro",
      "model": "HP LaserJet Pro M404dn"
    },
    "options": {
      "paper_size": "page_size_letter",
      "copies": 1,
      "total_pages": 2,
      "orientation": "portrait",
      "color_print": false,
      "double_sided": true,
      "print_all_pages": true,
      "pages_to_print": null,
      "scaling": 1.0,
      "custom_dimensions": null
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:35:00.000Z",
    "created_by": "key_abc123",
    "updated_by": "key_abc123"
  },
  "message": "Print job retrieved"
}

Error Codes

Code	Status	Description
`print_job.paper_size_required`	400	The paper size could not be determined from the document and `configuration.paper_size` was not supplied. Message: `Could not determine the paper size. Please specify configuration.paper_size.`
`no_compatible_printer`	400	No printer matches the document requirements
`unauthorized`	403	You don't have access to this print station
`location_access`	403	You don't have access to this location
`not_found`	404	Print job not found

Webhooks

Print job status changes trigger webhook events:

Event	Description
`cloud_printing.job.created`	New print job created
`cloud_printing.job.completed`	Print job completed successfully
`cloud_printing.job.failed`	Print job failed
`cloud_printing.job.canceled`	Print job canceled

Print Jobs

# Endpoints

# Required Scopes

# Create Print Job

# Request Body

# Parameters

# Document Data Formats

# Resource Types

# Configuration Options

# Auto-Selection Logic

# Custom Paper Size Example

# Minimal Request Example

# Response

# Update Print Job Status

# Status Transitions

# Request Examples

# Response

# List Print Jobs

# Query Parameters

# Example Request

# Response

# Retrieve Print Job

# Example Request

# Response

# Error Codes

# Webhooks

On this page

Endpoints

Required Scopes

Create Print Job

Request Body

Parameters

Document Data Formats

Resource Types

Configuration Options

Auto-Selection Logic

Custom Paper Size Example

Minimal Request Example

Response

Update Print Job Status

Status Transitions

Request Examples

Response

List Print Jobs

Query Parameters

Example Request

Response

Retrieve Print Job

Example Request

Response

Error Codes

Webhooks