Production Endpoints

Submit print jobs and receive print-ready files, register external productions, create save tokens server-side and query production status. All endpoints are POST requests with a JSON body to https://api.printess.com. See the Backend API Reference for authentication and how Try It Live works.

Produce Print Files

POSThttps://api.printess.com/production/produceuser

The main production endpoint: renders a template or saved design into print-ready files.

Renders a design into print-ready output (PDF by default) and returns immediately with a jobId and orderId — the rendering itself happens asynchronously. A shop integration typically calls this once per ordered line item after checkout, passing the save token it received from the buyer-side editor as templateName.

To get the result you either provide a callbackUrl (Printess POSTs the final result to it — see the Callback section below) or poll /production/status/get with the returned jobId.

Only templateName is strictly required, but we recommend always sending origin (makes your orders searchable) and externalOrderId (links the order to your shop order). For output configuration, the best practice is printSettingsTemplate: your production team maintains named print settings in the account portal and your code just forwards the name — no integration change needed when print requirements change. Explicit outputSettings in the request are only needed for special cases; keys defined in the print settings template take precedence over request values.

A 200 response means the job was queued, not that it finished. Wait for the callback or poll /production/status/get until isFinalStatus is true.

If a produce call is rejected, the payload and error are recorded and can be reviewed via /submission/errors/list.

Request Body

PropertyDescription
templateNamerequired
string
What to produce: a save token (st:...) from the buyer-side editor, or a template name from your account.
origin
string
Free text tag for this production request (e.g. your shop domain). Strongly recommended — it is your search key in /orders/list and the portal's order views.
externalOrderId
string
Your shop's order id. Stored with the order, returned in the callback and searchable — always send it in shop integrations.
callbackUrl
string
Absolute URL that receives exactly one POST when the job reaches its final state (success or failure) — see the Callback section. Must have a real hostname (no IP addresses, no localhost). Credentials embedded in the URL (https://user:pass@host/...) are sent as HTTP basic auth.
callbackHeaders
object
HTTP headers sent with the callback request, as a name to value map, e.g. { "X-Api-Key": "..." }. Only used together with callbackUrl.
printSettingsTemplate
string
Name of a print settings template maintained in the account portal (Print Settings page). Its values override the request's outputSettings key by key; it can also set the output type. An unknown name is rejected with an error.
outputSettings
OutputSettings
Explicit output settings, used for all output files that do not define their own.
24 nested properties
dpi
numberdefault: 300
Render resolution in dots per inch. In proof mode the dpi is always capped at 96.
jpegCompression
integerdefault: 90
JPEG quality (0-100) used when images are re-encoded. Only affects images that are JPEGs.
outputSpotColors
booleandefault: true
Output spot colors with their names. Set to false to convert spot colors to process colors.
outputLayers
booleandefault: false
Output the layers in the PDF file.
skipDefaultImages
booleandefault: false
Do not output frames that still hold their default / placeholder image.
outputDeviceCmyk
booleandefault: false
Emit raw device CMYK without an ICC profile. Never use this option unless you know exactly what you are doing.
cropToContent
booleandefault: false
Crop the output to the content: all PDF boxes (bleed, crop, trim) are shrunk to the content bounds.
taggedPdf
booleandefault: false
Emit PDF structure tags for frames and paragraphs that carry the pdfTag style property.
impositionName
string
Name of an imposition configured in the account portal. Note: an unknown name fails during rendering, not when submitting the job.
impositionUri
string
URL of an imposition definition file. Must be an absolute URL.
linearize
booleandefault: false
Linearize the output PDF ("fast web view").
proof
booleandefault: false
Create a proof PDF: adds a proof overlay and caps the resolution at 96 dpi. Once enabled, proof mode applies to every output file of the job.
shrink
booleandefault: false
Shrink the page boxes to the bounding box of the rendered text content — e.g. for engraving plates.
allowJpegConversion
booleandefault: false
Allow images with unused transparency (e.g. PNGs without actual transparency) to be re-encoded as JPEG. Smaller files, slightly reduced quality.
disableBleed
booleandefault: false
Ignore the document's bleed settings.
setPageNames
booleandefault: false
Write the spread names as page labels into the PDF.
setXmpMetaDataForEditableImages
booleandefault: false
Embed an XMP description tag containing editable into images placed in buyer-editable frames — lets pre-press tools distinguish customer artwork from design artwork.
outputPdfX4
booleandefault: false
Output the PDF as PDF/X-4.
optimizeImages
booleandefault: true
Trim images to fit their frames exactly — smaller files at the cost of some render speed. Currently always on.
upscale
booleandefault: false
Automatically AI-upscale low resolution buyer images when the required print size exceeds the source resolution. Not applied in proof mode.
upscaleProvider
stringdefault: Printess
Which upscaler to use.
Values: Printess CutoutPro
fps
numberdefault: 0
Frames per second — only for gif and movie output (allowed range 1-30).
width
integerdefault: 0
Maximum output width — only for animation / movie output. 0 derives the size from the document.
height
integerdefault: 0
Maximum output height — only for animation / movie output.
outputType
stringdefault: pdf
The output format. png and jpg produce one image per page; gif and movie additionally need outputSettings.fps. Any unrecognized value falls back to pdf.
Values: pdf png jpg gif movie
outputFiles
OutputFile[]
Produce specific documents of the template, each as its own output file. When omitted, Printess automatically produces the template's production documents. Each document name may appear only once.
3 nested properties
documentName
string
The document of the template to render.
outputSettings
OutputSettings
Output settings for this file. When set, it fully replaces the job-level outputSettings for this file (no per-key merge).
vdp
Vdp
Variable data for this file — overrides the job-level vdp.
vdp
Vdp
Form field values and variable data applied to the production.
4 nested properties
form
map<string, string>
Form field values, keyed by form field name (see /template/formFields/list). Overrides the values stored in the template / save token. Invalid select-list values silently fall back to the template default. Magic name: DOCUMENT_SIZE with a value like 100x150 resizes size-dependent documents.
data
map<string, string>
Single-record variable data. These are not form fields — they are the variables the template's text/script expressions read via data.<name>. A missing key resolves to an empty string.
records
map<string, string>[]
Multi-record variable data printing: the document is rendered once per record into one output file. Each entry is a data map. Magic key circulation in a record duplicates that record n times — the way to print different quantities per record.
templateStyle
string
Printess style text appended to the template's own style definitions — inject per-order style classes, e.g. .b1 { image: 1.jpg; }.
mergeTemplates
MergeTemplate[]
Merge other templates (or snippets) into the production document — e.g. merge a greeting card design into a print-sheet template. Only used when outputFiles is not specified.
10 nested properties
templateNamerequired
string
What to merge in: a template name, a save token (st:...), or a snippet reference (snippet~<id>).
documentName
string
The document of the merge template to take.
targetDocumentName
string
The document of the production template to merge into. Defaults to the primary document.
sourceSpreadIndex
integerdefault: 0
The spread of the merge document to start from.
targetSpreadIndex
integerdefault: 0
The spread of the target document to start merging into.
count
integer
How many spreads to take. Defaults to all spreads of the merge document.
usePublishedVersion
booleandefault: true
Take the published version of the merge template. Note: defaults to true here (unlike the job-level usePublishedVersion).
transferGlobalFormFieldValues
booleandefault: false
Copy the global form field values of this template onto the merged one.
templateNameIsSnippetId
booleandefault: false
Treat templateName as a snippet id and merge the snippet instead of a template.
mergeMode
string
Set to overlay to keep all existing layout-snippet frames of the target spread and place the merged content on top. Otherwise existing layout-snippet frames are replaced.
autoMerge
booleandefault: false
When the produced design is connected to a base template, automatically merge them as defined by the designer — without your code knowing the wiring.
usePublishedVersion
booleandefault: false
Produce the published version of the template. Only affects direct template names — save tokens contain their own frozen design.
copies
integerdefault: 1
The ordered quantity. Note: this does NOT duplicate pages or files — it is passed to fulfillment partners and filename placeholders. To render multiple instances use vdp.records.
orderMetaData
string
Meta data stored with the order and returned by /orders/list. Must be a string — to store structured data, pass serialized JSON (e.g. "{\"a\":1}").
meta
string
Meta data echoed back in the callback. Must be a string (serialize JSON yourself). Only delivered when callbackUrl is used — without a callback it is discarded; use orderMetaData for anything you want persisted.
productType
string
Free text product type for search and reporting. The special value Proof switches the job to proof mode (max 96 dpi, proof overlay).
contentTemplateName
string
A save token (st:...) to take buyer content from: the buyer-editable images and texts of that design are copied into this production's editable frames — e.g. to re-flow a customer's photos into a different layout.
combinePdfsIntoOne
booleandefault: false
Combine all produced PDF files into a single PDF.
failureRepeats
integerdefault: 1
How often the job is retried on errors. Maximum 3.
atomyxProfile
string
Path of an Atomyx pre-press profile to post-process the rendered PDFs. Requires a valid Atomyx access key configured in the account portal; results are delivered in addition to the normal output (result.ayx).
distributorName
string
Delivers the output files through a special distributor set up for your account by Printess. Contact Printess if you have special distribution needs.
exchangeTemplateName
string
Internal use only.

Try It Live

Requests are sent to https://api.printess.com/production/produce with your Service Token.

Code Example

Ready-to-use code with the minimal payload. Replace YOUR_PRINTESS_SERVICE_TOKEN with your Service Token.

// The main production endpoint: renders a template or saved design into print-ready files.
const response = await fetch("https://api.printess.com/production/produce", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "templateName": "YOUR_TEMPLATE_OR_SAVETOKEN",
    "origin": "your-shop.com",
    "externalOrderId": "YOUR_ORDER_ID"
  })
});

if (!response.ok) {
  throw new Error("Printess API error " + response.status + ": " + await response.text());
}

const result = await response.json();
console.log(result);
curl -X POST "https://api.printess.com/production/produce" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "templateName": "YOUR_TEMPLATE_OR_SAVETOKEN",
  "origin": "your-shop.com",
  "externalOrderId": "YOUR_ORDER_ID"
}'
// The main production endpoint: renders a template or saved design into print-ready files.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""templateName"": ""YOUR_TEMPLATE_OR_SAVETOKEN"",
  ""origin"": ""your-shop.com"",
  ""externalOrderId"": ""YOUR_ORDER_ID""
}";

using (var client = new HttpClient())
{
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_PRINTESS_SERVICE_TOKEN");

    var content = new StringContent(payload, Encoding.UTF8, "application/json");
    var response = await client.PostAsync("https://api.printess.com/production/produce", content);

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException("Printess API error " + (int)response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }

    var result = await response.Content.ReadAsStringAsync();
    Console.WriteLine(result);
}
<?php
// The main production endpoint: renders a template or saved design into print-ready files.
$payload = [
    'templateName' => 'YOUR_TEMPLATE_OR_SAVETOKEN',
    'origin' => 'your-shop.com',
    'externalOrderId' => 'YOUR_ORDER_ID',
];

$ch = curl_init('https://api.printess.com/production/produce');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException("Printess API error $status: $response");
}

$result = json_decode($response, true);
print_r($result);

Produce from a save token using a print settings template maintained in the account portal, and receive the result via callback.

const response = await fetch("https://api.printess.com/production/produce", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    templateName: "st:...",                       // save token from the buyer side editor
    origin: "your-shop.com",
    externalOrderId: "SO-1001",                   // your shop's order id
    callbackUrl: "https://your-shop.com/printess/callback",
    printSettingsTemplate: "default"              // maintained in the account portal
  })
});
const { jobId, orderId } = await response.json();
// Printess POSTs the final result (file URLs or error) to your callbackUrl.

Response

The job was accepted and queued.

PropertyDescription
jobId
string
Id of the queued render job — use it with /production/status/get and to correlate the callback.
orderId
string
Id of the created order — use it with /orders/list, /order/retry or /production/orders/files/zip.

Callback

When callbackUrl is set, Printess POSTs exactly one JSON document to it once the job reaches its final state — on success AND on failure (check isFailure). Respond with a 2xx status code; other responses are retried with increasing delays (about 5 minutes at first, later hourly/daily, up to 10 attempts).

The most important part is result.r: it maps each produced document name to its download URL. result.ff points to a JSON file with the evaluated form field values, result.oi.pageCounts has the page count per document, and result.oi.hasInvalidGlyph tells you a character could not be rendered with the chosen font — a useful quality signal. For png/jpg/gif/movie output the files are listed in result.p (one entry per page with d = document, u = URL, i = page index) instead of result.r.

{
  "jobId": "...",
  "orderId": "12345",
  "userId": "...",
  "templateName": "MyTemplate",
  "externalOrderId": "SO-1001",
  "meta": "{\"cart\":\"abc\"}",
  "isFailure": false,
  "failureDetails": null,
  "result": {
    "r":  { "Front": "https://.../..._1.pdf" },
    "p":  [],
    "ff": "https://.../..._formFields.json",
    "oi": { "hasInvalidGlyph": false, "pageCounts": { "Front": 2 } }
  }
}

Errors

Status / Code Meaning
406 (c: 101) templateName missing, or origin uses a reserved value.
406 (c: 102) Invalid callbackUrl (must be absolute, no localhost).
406 (c: 100) Unknown printSettingsTemplate.
406 (c: 600) The same document name appears twice in outputFiles.
406 (c: 601/202) Save token not found / already expired.
406 (c: 602/603) Template not found / has no published version.
406 (c: 604) Invalid impositionUri.
406 (c: 607) No producible document found in the template.
402 (c: 4) No credits left / plan issue.

Schemas

Copy-ready type definitions for the object types of this endpoint. All their properties are also listed in the tables above.

OutputSettings request
interface OutputSettings {
  dpi?: number;
  jpegCompression?: number;
  outputSpotColors?: boolean;
  outputLayers?: boolean;
  skipDefaultImages?: boolean;
  outputDeviceCmyk?: boolean;
  cropToContent?: boolean;
  taggedPdf?: boolean;
  impositionName?: string;
  impositionUri?: string;
  linearize?: boolean;
  proof?: boolean;
  shrink?: boolean;
  allowJpegConversion?: boolean;
  disableBleed?: boolean;
  setPageNames?: boolean;
  setXmpMetaDataForEditableImages?: boolean;
  outputPdfX4?: boolean;
  optimizeImages?: boolean;
  upscale?: boolean;
  upscaleProvider?: "Printess" | "CutoutPro";
  fps?: number;
  width?: number;
  height?: number;
}
public class OutputSettings
{
    [JsonPropertyName("dpi")]
    public double? Dpi { get; set; }

    [JsonPropertyName("jpegCompression")]
    public int? JpegCompression { get; set; }

    [JsonPropertyName("outputSpotColors")]
    public bool? OutputSpotColors { get; set; }

    [JsonPropertyName("outputLayers")]
    public bool? OutputLayers { get; set; }

    [JsonPropertyName("skipDefaultImages")]
    public bool? SkipDefaultImages { get; set; }

    [JsonPropertyName("outputDeviceCmyk")]
    public bool? OutputDeviceCmyk { get; set; }

    [JsonPropertyName("cropToContent")]
    public bool? CropToContent { get; set; }

    [JsonPropertyName("taggedPdf")]
    public bool? TaggedPdf { get; set; }

    [JsonPropertyName("impositionName")]
    public string ImpositionName { get; set; }

    [JsonPropertyName("impositionUri")]
    public string ImpositionUri { get; set; }

    [JsonPropertyName("linearize")]
    public bool? Linearize { get; set; }

    [JsonPropertyName("proof")]
    public bool? Proof { get; set; }

    [JsonPropertyName("shrink")]
    public bool? Shrink { get; set; }

    [JsonPropertyName("allowJpegConversion")]
    public bool? AllowJpegConversion { get; set; }

    [JsonPropertyName("disableBleed")]
    public bool? DisableBleed { get; set; }

    [JsonPropertyName("setPageNames")]
    public bool? SetPageNames { get; set; }

    [JsonPropertyName("setXmpMetaDataForEditableImages")]
    public bool? SetXmpMetaDataForEditableImages { get; set; }

    [JsonPropertyName("outputPdfX4")]
    public bool? OutputPdfX4 { get; set; }

    [JsonPropertyName("optimizeImages")]
    public bool? OptimizeImages { get; set; }

    [JsonPropertyName("upscale")]
    public bool? Upscale { get; set; }

    [JsonPropertyName("upscaleProvider")]
    public string UpscaleProvider { get; set; }

    [JsonPropertyName("fps")]
    public double? Fps { get; set; }

    [JsonPropertyName("width")]
    public int? Width { get; set; }

    [JsonPropertyName("height")]
    public int? Height { get; set; }
}
<?php

class OutputSettings
{
    public ?float $dpi = null;
    public ?int $jpegCompression = null;
    public ?bool $outputSpotColors = null;
    public ?bool $outputLayers = null;
    public ?bool $skipDefaultImages = null;
    public ?bool $outputDeviceCmyk = null;
    public ?bool $cropToContent = null;
    public ?bool $taggedPdf = null;
    public ?string $impositionName = null;
    public ?string $impositionUri = null;
    public ?bool $linearize = null;
    public ?bool $proof = null;
    public ?bool $shrink = null;
    public ?bool $allowJpegConversion = null;
    public ?bool $disableBleed = null;
    public ?bool $setPageNames = null;
    public ?bool $setXmpMetaDataForEditableImages = null;
    public ?bool $outputPdfX4 = null;
    public ?bool $optimizeImages = null;
    public ?bool $upscale = null;
    /** @var 'Printess'|'CutoutPro'|null */
    public ?string $upscaleProvider = null;
    public ?float $fps = null;
    public ?int $width = null;
    public ?int $height = null;
}
OutputFile request
interface OutputFile {
  documentName?: string;
  outputSettings?: OutputSettings;
  vdp?: Vdp;
}
public class OutputFile
{
    [JsonPropertyName("documentName")]
    public string DocumentName { get; set; }

    [JsonPropertyName("outputSettings")]
    public OutputSettings OutputSettings { get; set; }

    [JsonPropertyName("vdp")]
    public Vdp Vdp { get; set; }
}
<?php

class OutputFile
{
    public ?string $documentName = null;
    public ?OutputSettings $outputSettings = null;
    public ?Vdp $vdp = null;
}
Vdp request
interface Vdp {
  form?: Record<string, string>;
  data?: Record<string, string>;
  records?: Array<Record<string, string>>;
  templateStyle?: string;
}
public class Vdp
{
    [JsonPropertyName("form")]
    public Dictionary<string, string> Form { get; set; }

    [JsonPropertyName("data")]
    public Dictionary<string, string> Data { get; set; }

    [JsonPropertyName("records")]
    public List<Dictionary<string, string>> Records { get; set; }

    [JsonPropertyName("templateStyle")]
    public string TemplateStyle { get; set; }
}
<?php

class Vdp
{
    /** @var array<string, string>|null */
    public ?array $form = null;
    /** @var array<string, string>|null */
    public ?array $data = null;
    /** @var array<string, string>[]|null */
    public ?array $records = null;
    public ?string $templateStyle = null;
}
MergeTemplate request
interface MergeTemplate {
  templateName: string;
  documentName?: string;
  targetDocumentName?: string;
  sourceSpreadIndex?: number;
  targetSpreadIndex?: number;
  count?: number;
  usePublishedVersion?: boolean;
  transferGlobalFormFieldValues?: boolean;
  templateNameIsSnippetId?: boolean;
  mergeMode?: string;
}
public class MergeTemplate
{
    [JsonPropertyName("templateName")]
    public string TemplateName { get; set; }

    [JsonPropertyName("documentName")]
    public string DocumentName { get; set; }

    [JsonPropertyName("targetDocumentName")]
    public string TargetDocumentName { get; set; }

    [JsonPropertyName("sourceSpreadIndex")]
    public int? SourceSpreadIndex { get; set; }

    [JsonPropertyName("targetSpreadIndex")]
    public int? TargetSpreadIndex { get; set; }

    [JsonPropertyName("count")]
    public int? Count { get; set; }

    [JsonPropertyName("usePublishedVersion")]
    public bool? UsePublishedVersion { get; set; }

    [JsonPropertyName("transferGlobalFormFieldValues")]
    public bool? TransferGlobalFormFieldValues { get; set; }

    [JsonPropertyName("templateNameIsSnippetId")]
    public bool? TemplateNameIsSnippetId { get; set; }

    [JsonPropertyName("mergeMode")]
    public string MergeMode { get; set; }
}
<?php

class MergeTemplate
{
    public string $templateName;
    public ?string $documentName = null;
    public ?string $targetDocumentName = null;
    public ?int $sourceSpreadIndex = null;
    public ?int $targetSpreadIndex = null;
    public ?int $count = null;
    public ?bool $usePublishedVersion = null;
    public ?bool $transferGlobalFormFieldValues = null;
    public ?bool $templateNameIsSnippetId = null;
    public ?string $mergeMode = null;
}

Produce (Simple)

POSThttps://api.printess.com/production/produce/simpleuser

Minimal production call: template + your order id, PDF at the given dpi.

A deliberately simple variant of /production/produce: renders the template or save token as PDF at the given resolution — no other options. The account-level callback URL (configurable in the portal) still applies if set.

Use /production/produce when you need callbacks per call, form field values, merges or non-PDF output.

Request Body

PropertyDescription
templateNamerequired
string
The template name or save token (st:...) to produce.
externalOrderIdrequired
string
Your shop's order id. Required on this endpoint.
origin
string
Free text tag for searching your orders.
dpi
integerdefault: 300
The output resolution.

Try It Live

Requests are sent to https://api.printess.com/production/produce/simple with your Service Token.

Code Example

Ready-to-use code with the minimal payload. Replace YOUR_PRINTESS_SERVICE_TOKEN with your Service Token.

// Minimal production call: template + your order id, PDF at the given dpi.
const response = await fetch("https://api.printess.com/production/produce/simple", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "templateName": "YOUR_TEMPLATE_OR_SAVETOKEN",
    "externalOrderId": "YOUR_ORDER_ID"
  })
});

if (!response.ok) {
  throw new Error("Printess API error " + response.status + ": " + await response.text());
}

const result = await response.json();
console.log(result);
curl -X POST "https://api.printess.com/production/produce/simple" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "templateName": "YOUR_TEMPLATE_OR_SAVETOKEN",
  "externalOrderId": "YOUR_ORDER_ID"
}'
// Minimal production call: template + your order id, PDF at the given dpi.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""templateName"": ""YOUR_TEMPLATE_OR_SAVETOKEN"",
  ""externalOrderId"": ""YOUR_ORDER_ID""
}";

using (var client = new HttpClient())
{
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_PRINTESS_SERVICE_TOKEN");

    var content = new StringContent(payload, Encoding.UTF8, "application/json");
    var response = await client.PostAsync("https://api.printess.com/production/produce/simple", content);

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException("Printess API error " + (int)response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }

    var result = await response.Content.ReadAsStringAsync();
    Console.WriteLine(result);
}
<?php
// Minimal production call: template + your order id, PDF at the given dpi.
$payload = [
    'templateName' => 'YOUR_TEMPLATE_OR_SAVETOKEN',
    'externalOrderId' => 'YOUR_ORDER_ID',
];

$ch = curl_init('https://api.printess.com/production/produce/simple');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException("Printess API error $status: $response");
}

$result = json_decode($response, true);
print_r($result);

Response

PropertyDescription
jobId
string
Id of the queued render job — poll /production/status/get.
orderId
string
Id of the created order.

Errors

Status / Code Meaning
406 (c: 101) templateName or externalOrderId missing.

Create Save Token

POSThttps://api.printess.com/production/savetoken/createshop

Create a saved design server-side — with form fields, merges, images and actions.

Creates a save token (a persisted design snapshot, the same artifact the buyer-side editor produces) entirely from your backend. Use it when your system composes the design instead of a buyer: pre-filled form fields, merged templates or layout snippets, injected images, geometry adjustments.

The returned save token can be produced via /production/produce, opened in the editor, or handed to the buyer-side editor for further editing. The response also contains a ready-to-use thumbnail URL.

When you use mergeTemplates, contentTemplateName or autoMerge, the design is fully materialized by the render engine — expect the call to take a few seconds. Plain form-field calls are fast (see also /production/savetoken/create/with/formfields, which this endpoint uses automatically for simple requests).

Request Body

PropertyDescription
templateNamerequired
string
The base of the new design: a template name or an existing save token (st:...).
usePublishedVersion
booleandefault: true
Use the published version of the template. Note: defaults to true on this endpoint.
formFields
map<string, string>
Form field values to bake into the design, keyed by form field name (see /template/formFields/list). DOCUMENT_SIZE accepts a WxH value like 100x150.
actions
Action[]
Actions executed on the design before it is stored, in order. Each action is an object with a type discriminator plus type-specific properties (see the nested list). Actions you supply run before the formFields values are applied.
7 nested properties
setFormFieldValueAction
action
Set a form field: {"type": "setFormFieldValueAction", "formFieldName": "...", "formFieldValue": "..."}.
replaceImageByUrl
action
Upload an image from a URL and place it into a frame: {"type": "replaceImageByUrl", "targetFrameTitle": "...", "imageUrl": "https://..."}. The frame is identified by its title.
replaceImageByName
action
Place an already uploaded image into a frame: {"type": "replaceImageByName", "targetFrameTitle": "...", "imageName": "..."}.
addImage
action
Upload an image into the design's image list without placing it: {"type": "addImage", "imageUrl": "https://..."}. Optional: importImageName, imageGroupName.
addImages
action
Upload several images: {"type": "addImages", "imageUrls": ["https://..."]}.
adjustFrameGeometry
action
Move / resize / rotate a frame identified by its title: {"type": "adjustFrameGeometry", "targetFrameTitle": "...", "width": {...}, "rotation": 90}.
adjustDocument
action
Change the document size: {"type": "adjustDocument", "width": 100, "height": 150, "unit": "mm"}.
mergeTemplates
MergeTemplate[]
Templates or snippets to merge into the design (same structure as in /production/produce).
10 nested properties
templateNamerequired
string
What to merge in: a template name, a save token (st:...), or a snippet reference (snippet~<id>).
documentName
string
The document of the merge template to take.
targetDocumentName
string
The document of the production template to merge into. Defaults to the primary document.
sourceSpreadIndex
integerdefault: 0
The spread of the merge document to start from.
targetSpreadIndex
integerdefault: 0
The spread of the target document to start merging into.
count
integer
How many spreads to take. Defaults to all spreads of the merge document.
usePublishedVersion
booleandefault: true
Take the published version of the merge template. Note: defaults to true here (unlike the job-level usePublishedVersion).
transferGlobalFormFieldValues
booleandefault: false
Copy the global form field values of this template onto the merged one.
templateNameIsSnippetId
booleandefault: false
Treat templateName as a snippet id and merge the snippet instead of a template.
mergeMode
string
Set to overlay to keep all existing layout-snippet frames of the target spread and place the merged content on top. Otherwise existing layout-snippet frames are replaced.
contentTemplateName
string
A save token (st:...) to take buyer content (editable images and texts) from.
autoMerge
booleandefault: false
When the template is connected to a base template, automatically merge them as defined by the designer.
shopInfo
object
Shop identifiers stored with the save token — used to group buyer uploads and to find tokens later via /savetoken/list.
3 nested properties
basketId
string
Your shop's basket / cart id. Buyer uploads are grouped and cleaned up by this id, so set it to a real value.
userId
string
Your shop's customer id.
userDisplay
string
Human-readable customer name for the back office.

Try It Live

Requests are sent to https://api.printess.com/production/savetoken/create with your Service Token.

Code Example

Ready-to-use code with the minimal payload. Replace YOUR_PRINTESS_SERVICE_TOKEN with your Service Token.

// Create a saved design server-side — with form fields, merges, images and actions.
const response = await fetch("https://api.printess.com/production/savetoken/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "templateName": "YOUR_TEMPLATE_NAME",
    "formFields": {
      "EXAMPLE_FIELD": "value"
    }
  })
});

if (!response.ok) {
  throw new Error("Printess API error " + response.status + ": " + await response.text());
}

const result = await response.json();
console.log(result);
curl -X POST "https://api.printess.com/production/savetoken/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "templateName": "YOUR_TEMPLATE_NAME",
  "formFields": {
    "EXAMPLE_FIELD": "value"
  }
}'
// Create a saved design server-side — with form fields, merges, images and actions.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""templateName"": ""YOUR_TEMPLATE_NAME"",
  ""formFields"": {
    ""EXAMPLE_FIELD"": ""value""
  }
}";

using (var client = new HttpClient())
{
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_PRINTESS_SERVICE_TOKEN");

    var content = new StringContent(payload, Encoding.UTF8, "application/json");
    var response = await client.PostAsync("https://api.printess.com/production/savetoken/create", content);

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException("Printess API error " + (int)response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }

    var result = await response.Content.ReadAsStringAsync();
    Console.WriteLine(result);
}
<?php
// Create a saved design server-side — with form fields, merges, images and actions.
$payload = [
    'templateName' => 'YOUR_TEMPLATE_NAME',
    'formFields' => [
        'EXAMPLE_FIELD' => 'value',
    ],
];

$ch = curl_init('https://api.printess.com/production/savetoken/create');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException("Printess API error $status: $response");
}

$result = json_decode($response, true);
print_r($result);

Response

PropertyDescription
saveToken
string
The created save token (st:...) — usable as templateName in the production endpoints and in the editor.
thumbnailUrl
string
URL of a preview image of the design (rendered on first access).

Errors

Status / Code Meaning
406 (c: 102) templateName missing.
406 (c: 601/202) Base save token not found / expired.
406 (c: 1) Invalid DOCUMENT_SIZE value.
500 The design could not be materialized — the message contains the render error.

Schemas

Copy-ready type definitions for the object types of this endpoint. All their properties are also listed in the tables above.

Action request
interface Action {
  setFormFieldValueAction?: object;
  replaceImageByUrl?: object;
  replaceImageByName?: object;
  addImage?: object;
  addImages?: object;
  adjustFrameGeometry?: object;
  adjustDocument?: object;
}
public class Action
{
    [JsonPropertyName("setFormFieldValueAction")]
    public object SetFormFieldValueAction { get; set; }

    [JsonPropertyName("replaceImageByUrl")]
    public object ReplaceImageByUrl { get; set; }

    [JsonPropertyName("replaceImageByName")]
    public object ReplaceImageByName { get; set; }

    [JsonPropertyName("addImage")]
    public object AddImage { get; set; }

    [JsonPropertyName("addImages")]
    public object AddImages { get; set; }

    [JsonPropertyName("adjustFrameGeometry")]
    public object AdjustFrameGeometry { get; set; }

    [JsonPropertyName("adjustDocument")]
    public object AdjustDocument { get; set; }
}
<?php

class Action
{
    public ?object $setFormFieldValueAction = null;
    public ?object $replaceImageByUrl = null;
    public ?object $replaceImageByName = null;
    public ?object $addImage = null;
    public ?object $addImages = null;
    public ?object $adjustFrameGeometry = null;
    public ?object $adjustDocument = null;
}
MergeTemplate request
interface MergeTemplate {
  templateName: string;
  documentName?: string;
  targetDocumentName?: string;
  sourceSpreadIndex?: number;
  targetSpreadIndex?: number;
  count?: number;
  usePublishedVersion?: boolean;
  transferGlobalFormFieldValues?: boolean;
  templateNameIsSnippetId?: boolean;
  mergeMode?: string;
}
public class MergeTemplate
{
    [JsonPropertyName("templateName")]
    public string TemplateName { get; set; }

    [JsonPropertyName("documentName")]
    public string DocumentName { get; set; }

    [JsonPropertyName("targetDocumentName")]
    public string TargetDocumentName { get; set; }

    [JsonPropertyName("sourceSpreadIndex")]
    public int? SourceSpreadIndex { get; set; }

    [JsonPropertyName("targetSpreadIndex")]
    public int? TargetSpreadIndex { get; set; }

    [JsonPropertyName("count")]
    public int? Count { get; set; }

    [JsonPropertyName("usePublishedVersion")]
    public bool? UsePublishedVersion { get; set; }

    [JsonPropertyName("transferGlobalFormFieldValues")]
    public bool? TransferGlobalFormFieldValues { get; set; }

    [JsonPropertyName("templateNameIsSnippetId")]
    public bool? TemplateNameIsSnippetId { get; set; }

    [JsonPropertyName("mergeMode")]
    public string MergeMode { get; set; }
}
<?php

class MergeTemplate
{
    public string $templateName;
    public ?string $documentName = null;
    public ?string $targetDocumentName = null;
    public ?int $sourceSpreadIndex = null;
    public ?int $targetSpreadIndex = null;
    public ?int $count = null;
    public ?bool $usePublishedVersion = null;
    public ?bool $transferGlobalFormFieldValues = null;
    public ?bool $templateNameIsSnippetId = null;
    public ?string $mergeMode = null;
}
shopInfo request
interface ShopInfo {
  basketId?: string;
  userId?: string;
  userDisplay?: string;
}
public class ShopInfo
{
    [JsonPropertyName("basketId")]
    public string BasketId { get; set; }

    [JsonPropertyName("userId")]
    public string UserId { get; set; }

    [JsonPropertyName("userDisplay")]
    public string UserDisplay { get; set; }
}
<?php

class ShopInfo
{
    public ?string $basketId = null;
    public ?string $userId = null;
    public ?string $userDisplay = null;
}

Create Save Token with Form Fields

POSThttps://api.printess.com/production/savetoken/create/with/formfieldsshop

Fast save token creation from a template plus form field values.

The lightweight save token creator: loads the template (or an existing save token), applies form field values and actions, and stores the result as a new save token. No merging or design materialization happens, which makes this call fast.

This is the endpoint of choice for “create a personalized design from a template and a set of option values” — e.g. generating designs for every product variant.

Request Body

PropertyDescription
templateNamerequired
string
The base: a template name or an existing save token (st:...).
formFields
map<string, string>
Form field values keyed by form field name (see /template/formFields/list).
usePublishedVersion
booleandefault: true
Use the published version of the template.
actions
Action[]
Actions executed on the design before it is stored, in order. Each action is an object with a type discriminator plus type-specific properties (see the nested list). Actions you supply run before the formFields values are applied.
7 nested properties
setFormFieldValueAction
action
Set a form field: {"type": "setFormFieldValueAction", "formFieldName": "...", "formFieldValue": "..."}.
replaceImageByUrl
action
Upload an image from a URL and place it into a frame: {"type": "replaceImageByUrl", "targetFrameTitle": "...", "imageUrl": "https://..."}. The frame is identified by its title.
replaceImageByName
action
Place an already uploaded image into a frame: {"type": "replaceImageByName", "targetFrameTitle": "...", "imageName": "..."}.
addImage
action
Upload an image into the design's image list without placing it: {"type": "addImage", "imageUrl": "https://..."}. Optional: importImageName, imageGroupName.
addImages
action
Upload several images: {"type": "addImages", "imageUrls": ["https://..."]}.
adjustFrameGeometry
action
Move / resize / rotate a frame identified by its title: {"type": "adjustFrameGeometry", "targetFrameTitle": "...", "width": {...}, "rotation": 90}.
adjustDocument
action
Change the document size: {"type": "adjustDocument", "width": 100, "height": 150, "unit": "mm"}.
shopInfo
object
Shop identifiers stored with the save token — used to group buyer uploads and to find tokens later via /savetoken/list.
3 nested properties
basketId
string
Your shop's basket / cart id. Buyer uploads are grouped and cleaned up by this id, so set it to a real value.
userId
string
Your shop's customer id.
userDisplay
string
Human-readable customer name for the back office.

Try It Live

Requests are sent to https://api.printess.com/production/savetoken/create/with/formfields with your Service Token.

Code Example

Ready-to-use code with the minimal payload. Replace YOUR_PRINTESS_SERVICE_TOKEN with your Service Token.

// Fast save token creation from a template plus form field values.
const response = await fetch("https://api.printess.com/production/savetoken/create/with/formfields", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "templateName": "YOUR_TEMPLATE_NAME",
    "formFields": {
      "EXAMPLE_FIELD": "value"
    }
  })
});

if (!response.ok) {
  throw new Error("Printess API error " + response.status + ": " + await response.text());
}

const result = await response.json();
console.log(result);
curl -X POST "https://api.printess.com/production/savetoken/create/with/formfields" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "templateName": "YOUR_TEMPLATE_NAME",
  "formFields": {
    "EXAMPLE_FIELD": "value"
  }
}'
// Fast save token creation from a template plus form field values.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""templateName"": ""YOUR_TEMPLATE_NAME"",
  ""formFields"": {
    ""EXAMPLE_FIELD"": ""value""
  }
}";

using (var client = new HttpClient())
{
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_PRINTESS_SERVICE_TOKEN");

    var content = new StringContent(payload, Encoding.UTF8, "application/json");
    var response = await client.PostAsync("https://api.printess.com/production/savetoken/create/with/formfields", content);

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException("Printess API error " + (int)response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }

    var result = await response.Content.ReadAsStringAsync();
    Console.WriteLine(result);
}
<?php
// Fast save token creation from a template plus form field values.
$payload = [
    'templateName' => 'YOUR_TEMPLATE_NAME',
    'formFields' => [
        'EXAMPLE_FIELD' => 'value',
    ],
];

$ch = curl_init('https://api.printess.com/production/savetoken/create/with/formfields');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException("Printess API error $status: $response");
}

$result = json_decode($response, true);
print_r($result);

Create and produce a personalized design (JavaScript)

Create a save token with form field values, then produce it.

const baseUrl = "https://api.printess.com";
const headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
};

// 1) bake form field values into a new save token
const tokenResponse = await fetch(baseUrl + "/production/savetoken/create/with/formfields", {
  method: "POST",
  headers,
  body: JSON.stringify({
    templateName: "Mug",
    formFields: { Name: "Jane", Color: "red" },
    shopInfo: { basketId: "cart-42", userId: "customer-7" }
  })
});
const { saveToken, thumbnailUrl } = await tokenResponse.json();

// 2) produce it
const produceResponse = await fetch(baseUrl + "/production/produce", {
  method: "POST",
  headers,
  body: JSON.stringify({
    templateName: saveToken,
    origin: "your-shop.com",
    externalOrderId: "SO-1001"
  })
});
const { jobId, orderId } = await produceResponse.json();

Response

PropertyDescription
saveToken
string
The created save token (st:...).
thumbnailUrl
string
URL of a preview image of the design.

Errors

Status / Code Meaning
406 (c: 102) templateName missing.
406 (c: 601/202) Base save token not found / expired.
406 (c: 1) Invalid DOCUMENT_SIZE value.

Schemas

Copy-ready type definitions for the object types of this endpoint. All their properties are also listed in the tables above.

Action request
interface Action {
  setFormFieldValueAction?: object;
  replaceImageByUrl?: object;
  replaceImageByName?: object;
  addImage?: object;
  addImages?: object;
  adjustFrameGeometry?: object;
  adjustDocument?: object;
}
public class Action
{
    [JsonPropertyName("setFormFieldValueAction")]
    public object SetFormFieldValueAction { get; set; }

    [JsonPropertyName("replaceImageByUrl")]
    public object ReplaceImageByUrl { get; set; }

    [JsonPropertyName("replaceImageByName")]
    public object ReplaceImageByName { get; set; }

    [JsonPropertyName("addImage")]
    public object AddImage { get; set; }

    [JsonPropertyName("addImages")]
    public object AddImages { get; set; }

    [JsonPropertyName("adjustFrameGeometry")]
    public object AdjustFrameGeometry { get; set; }

    [JsonPropertyName("adjustDocument")]
    public object AdjustDocument { get; set; }
}
<?php

class Action
{
    public ?object $setFormFieldValueAction = null;
    public ?object $replaceImageByUrl = null;
    public ?object $replaceImageByName = null;
    public ?object $addImage = null;
    public ?object $addImages = null;
    public ?object $adjustFrameGeometry = null;
    public ?object $adjustDocument = null;
}
shopInfo request
interface ShopInfo {
  basketId?: string;
  userId?: string;
  userDisplay?: string;
}
public class ShopInfo
{
    [JsonPropertyName("basketId")]
    public string BasketId { get; set; }

    [JsonPropertyName("userId")]
    public string UserId { get; set; }

    [JsonPropertyName("userDisplay")]
    public string UserDisplay { get; set; }
}
<?php

class ShopInfo
{
    public ?string $basketId = null;
    public ?string $userId = null;
    public ?string $userDisplay = null;
}

Produce Shop Proof

POSThttps://api.printess.com/production/shop/proofshop

Low-resolution proof rendering, callable with a shop token from the storefront.

Renders a proof (max 96 dpi, with proof overlay) of a design — intended to be called from the storefront so a buyer can view a proof PDF of their design before ordering. The request body is the same as /production/produce; proof mode and the proof resolution/quality configured for your account are enforced automatically.

This feature must be enabled for your account (account setting shop_proof) — otherwise the call is rejected.

The call is asynchronous like all production calls: poll /production/status/pdf/get with the returned jobId to get the proof PDF URL.

Request Body

PropertyDescription
templateNamerequired
string
The save token (st:...) or template name to proof.
origin
string
Free text tag for searching your orders.
vdp
Vdp
Form field values / variable data (same structure as /production/produce).
4 nested properties
form
map<string, string>
Form field values, keyed by form field name (see /template/formFields/list). Overrides the values stored in the template / save token. Invalid select-list values silently fall back to the template default. Magic name: DOCUMENT_SIZE with a value like 100x150 resizes size-dependent documents.
data
map<string, string>
Single-record variable data. These are not form fields — they are the variables the template's text/script expressions read via data.<name>. A missing key resolves to an empty string.
records
map<string, string>[]
Multi-record variable data printing: the document is rendered once per record into one output file. Each entry is a data map. Magic key circulation in a record duplicates that record n times — the way to print different quantities per record.
templateStyle
string
Printess style text appended to the template's own style definitions — inject per-order style classes, e.g. .b1 { image: 1.jpg; }.
outputSettings
OutputSettings
Output settings — proof is forced on and the resolution is capped at 96 dpi regardless of what you send.
24 nested properties
dpi
numberdefault: 300
Render resolution in dots per inch. In proof mode the dpi is always capped at 96.
jpegCompression
integerdefault: 90
JPEG quality (0-100) used when images are re-encoded. Only affects images that are JPEGs.
outputSpotColors
booleandefault: true
Output spot colors with their names. Set to false to convert spot colors to process colors.
outputLayers
booleandefault: false
Output the layers in the PDF file.
skipDefaultImages
booleandefault: false
Do not output frames that still hold their default / placeholder image.
outputDeviceCmyk
booleandefault: false
Emit raw device CMYK without an ICC profile. Never use this option unless you know exactly what you are doing.
cropToContent
booleandefault: false
Crop the output to the content: all PDF boxes (bleed, crop, trim) are shrunk to the content bounds.
taggedPdf
booleandefault: false
Emit PDF structure tags for frames and paragraphs that carry the pdfTag style property.
impositionName
string
Name of an imposition configured in the account portal. Note: an unknown name fails during rendering, not when submitting the job.
impositionUri
string
URL of an imposition definition file. Must be an absolute URL.
linearize
booleandefault: false
Linearize the output PDF ("fast web view").
proof
booleandefault: false
Create a proof PDF: adds a proof overlay and caps the resolution at 96 dpi. Once enabled, proof mode applies to every output file of the job.
shrink
booleandefault: false
Shrink the page boxes to the bounding box of the rendered text content — e.g. for engraving plates.
allowJpegConversion
booleandefault: false
Allow images with unused transparency (e.g. PNGs without actual transparency) to be re-encoded as JPEG. Smaller files, slightly reduced quality.
disableBleed
booleandefault: false
Ignore the document's bleed settings.
setPageNames
booleandefault: false
Write the spread names as page labels into the PDF.
setXmpMetaDataForEditableImages
booleandefault: false
Embed an XMP description tag containing editable into images placed in buyer-editable frames — lets pre-press tools distinguish customer artwork from design artwork.
outputPdfX4
booleandefault: false
Output the PDF as PDF/X-4.
optimizeImages
booleandefault: true
Trim images to fit their frames exactly — smaller files at the cost of some render speed. Currently always on.
upscale
booleandefault: false
Automatically AI-upscale low resolution buyer images when the required print size exceeds the source resolution. Not applied in proof mode.
upscaleProvider
stringdefault: Printess
Which upscaler to use.
Values: Printess CutoutPro
fps
numberdefault: 0
Frames per second — only for gif and movie output (allowed range 1-30).
width
integerdefault: 0
Maximum output width — only for animation / movie output. 0 derives the size from the document.
height
integerdefault: 0
Maximum output height — only for animation / movie output.

Try It Live

Requests are sent to https://api.printess.com/production/shop/proof with your Service Token.

Code Example

Ready-to-use code with the minimal payload. Replace YOUR_PRINTESS_SERVICE_TOKEN with your Service Token.

// Low-resolution proof rendering, callable with a shop token from the storefront.
const response = await fetch("https://api.printess.com/production/shop/proof", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "templateName": "YOUR_TEMPLATE_OR_SAVETOKEN"
  })
});

if (!response.ok) {
  throw new Error("Printess API error " + response.status + ": " + await response.text());
}

const result = await response.json();
console.log(result);
curl -X POST "https://api.printess.com/production/shop/proof" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "templateName": "YOUR_TEMPLATE_OR_SAVETOKEN"
}'
// Low-resolution proof rendering, callable with a shop token from the storefront.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""templateName"": ""YOUR_TEMPLATE_OR_SAVETOKEN""
}";

using (var client = new HttpClient())
{
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_PRINTESS_SERVICE_TOKEN");

    var content = new StringContent(payload, Encoding.UTF8, "application/json");
    var response = await client.PostAsync("https://api.printess.com/production/shop/proof", content);

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException("Printess API error " + (int)response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }

    var result = await response.Content.ReadAsStringAsync();
    Console.WriteLine(result);
}
<?php
// Low-resolution proof rendering, callable with a shop token from the storefront.
$payload = [
    'templateName' => 'YOUR_TEMPLATE_OR_SAVETOKEN',
];

$ch = curl_init('https://api.printess.com/production/shop/proof');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException("Printess API error $status: $response");
}

$result = json_decode($response, true);
print_r($result);

Response

PropertyDescription
jobId
string
Id of the queued proof job — poll /production/status/pdf/get.
orderId
string
Id of the created (proof) order.

Errors

Status / Code Meaning
406 (c: 403) Proof production is not enabled for this account.

Schemas

Copy-ready type definitions for the object types of this endpoint. All their properties are also listed in the tables above.

Vdp request
interface Vdp {
  form?: Record<string, string>;
  data?: Record<string, string>;
  records?: Array<Record<string, string>>;
  templateStyle?: string;
}
public class Vdp
{
    [JsonPropertyName("form")]
    public Dictionary<string, string> Form { get; set; }

    [JsonPropertyName("data")]
    public Dictionary<string, string> Data { get; set; }

    [JsonPropertyName("records")]
    public List<Dictionary<string, string>> Records { get; set; }

    [JsonPropertyName("templateStyle")]
    public string TemplateStyle { get; set; }
}
<?php

class Vdp
{
    /** @var array<string, string>|null */
    public ?array $form = null;
    /** @var array<string, string>|null */
    public ?array $data = null;
    /** @var array<string, string>[]|null */
    public ?array $records = null;
    public ?string $templateStyle = null;
}
OutputSettings request
interface OutputSettings {
  dpi?: number;
  jpegCompression?: number;
  outputSpotColors?: boolean;
  outputLayers?: boolean;
  skipDefaultImages?: boolean;
  outputDeviceCmyk?: boolean;
  cropToContent?: boolean;
  taggedPdf?: boolean;
  impositionName?: string;
  impositionUri?: string;
  linearize?: boolean;
  proof?: boolean;
  shrink?: boolean;
  allowJpegConversion?: boolean;
  disableBleed?: boolean;
  setPageNames?: boolean;
  setXmpMetaDataForEditableImages?: boolean;
  outputPdfX4?: boolean;
  optimizeImages?: boolean;
  upscale?: boolean;
  upscaleProvider?: "Printess" | "CutoutPro";
  fps?: number;
  width?: number;
  height?: number;
}
public class OutputSettings
{
    [JsonPropertyName("dpi")]
    public double? Dpi { get; set; }

    [JsonPropertyName("jpegCompression")]
    public int? JpegCompression { get; set; }

    [JsonPropertyName("outputSpotColors")]
    public bool? OutputSpotColors { get; set; }

    [JsonPropertyName("outputLayers")]
    public bool? OutputLayers { get; set; }

    [JsonPropertyName("skipDefaultImages")]
    public bool? SkipDefaultImages { get; set; }

    [JsonPropertyName("outputDeviceCmyk")]
    public bool? OutputDeviceCmyk { get; set; }

    [JsonPropertyName("cropToContent")]
    public bool? CropToContent { get; set; }

    [JsonPropertyName("taggedPdf")]
    public bool? TaggedPdf { get; set; }

    [JsonPropertyName("impositionName")]
    public string ImpositionName { get; set; }

    [JsonPropertyName("impositionUri")]
    public string ImpositionUri { get; set; }

    [JsonPropertyName("linearize")]
    public bool? Linearize { get; set; }

    [JsonPropertyName("proof")]
    public bool? Proof { get; set; }

    [JsonPropertyName("shrink")]
    public bool? Shrink { get; set; }

    [JsonPropertyName("allowJpegConversion")]
    public bool? AllowJpegConversion { get; set; }

    [JsonPropertyName("disableBleed")]
    public bool? DisableBleed { get; set; }

    [JsonPropertyName("setPageNames")]
    public bool? SetPageNames { get; set; }

    [JsonPropertyName("setXmpMetaDataForEditableImages")]
    public bool? SetXmpMetaDataForEditableImages { get; set; }

    [JsonPropertyName("outputPdfX4")]
    public bool? OutputPdfX4 { get; set; }

    [JsonPropertyName("optimizeImages")]
    public bool? OptimizeImages { get; set; }

    [JsonPropertyName("upscale")]
    public bool? Upscale { get; set; }

    [JsonPropertyName("upscaleProvider")]
    public string UpscaleProvider { get; set; }

    [JsonPropertyName("fps")]
    public double? Fps { get; set; }

    [JsonPropertyName("width")]
    public int? Width { get; set; }

    [JsonPropertyName("height")]
    public int? Height { get; set; }
}
<?php

class OutputSettings
{
    public ?float $dpi = null;
    public ?int $jpegCompression = null;
    public ?bool $outputSpotColors = null;
    public ?bool $outputLayers = null;
    public ?bool $skipDefaultImages = null;
    public ?bool $outputDeviceCmyk = null;
    public ?bool $cropToContent = null;
    public ?bool $taggedPdf = null;
    public ?string $impositionName = null;
    public ?string $impositionUri = null;
    public ?bool $linearize = null;
    public ?bool $proof = null;
    public ?bool $shrink = null;
    public ?bool $allowJpegConversion = null;
    public ?bool $disableBleed = null;
    public ?bool $setPageNames = null;
    public ?bool $setXmpMetaDataForEditableImages = null;
    public ?bool $outputPdfX4 = null;
    public ?bool $optimizeImages = null;
    public ?bool $upscale = null;
    /** @var 'Printess'|'CutoutPro'|null */
    public ?string $upscaleProvider = null;
    public ?float $fps = null;
    public ?int $width = null;
    public ?int $height = null;
}

Register External Production

POSThttps://api.printess.com/production/externaluser

Register an order that is produced outside Printess and read the design’s form field values.

Registers a finished order without rendering anything — for integrations that produce the artwork themselves but still want the order recorded in Printess (reporting, accounting) and need the customer’s chosen form field values.

When templateName is a save token, the response includes the design’s stored form fields. Prefer /production/v2/external where possible: it returns fully evaluated values and image exchange data.

Request Body

PropertyDescription
templateNamerequired
string
A save token (st:...) or template name. Only save tokens yield form field values in the response.
originrequired
string
Free text tag for searching your orders. Required on this endpoint.
externalOrderId
string
Your shop's order id.
productType
string
Free text product type.
orderMetaData
string
Meta data stored with the order (string; serialize JSON yourself).

Try It Live

Requests are sent to https://api.printess.com/production/external with your Service Token.

Code Example

Ready-to-use code with the minimal payload. Replace YOUR_PRINTESS_SERVICE_TOKEN with your Service Token.

// Register an order that is produced outside Printess and read the design's form field values.
const response = await fetch("https://api.printess.com/production/external", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "templateName": "st:YOUR_SAVE_TOKEN",
    "origin": "your-shop.com"
  })
});

if (!response.ok) {
  throw new Error("Printess API error " + response.status + ": " + await response.text());
}

const result = await response.json();
console.log(result);
curl -X POST "https://api.printess.com/production/external" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "templateName": "st:YOUR_SAVE_TOKEN",
  "origin": "your-shop.com"
}'
// Register an order that is produced outside Printess and read the design's form field values.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""templateName"": ""st:YOUR_SAVE_TOKEN"",
  ""origin"": ""your-shop.com""
}";

using (var client = new HttpClient())
{
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_PRINTESS_SERVICE_TOKEN");

    var content = new StringContent(payload, Encoding.UTF8, "application/json");
    var response = await client.PostAsync("https://api.printess.com/production/external", content);

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException("Printess API error " + (int)response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }

    var result = await response.Content.ReadAsStringAsync();
    Console.WriteLine(result);
}
<?php
// Register an order that is produced outside Printess and read the design's form field values.
$payload = [
    'templateName' => 'st:YOUR_SAVE_TOKEN',
    'origin' => 'your-shop.com',
];

$ch = curl_init('https://api.printess.com/production/external');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException("Printess API error $status: $response");
}

$result = json_decode($response, true);
print_r($result);

Response

PropertyDescription
orderId
string
Id of the registered order.
formFields
FormFields
The design's stored form fields (same structure as /template/formFields/list) when a save token was passed — otherwise null.

Errors

Status / Code Meaning
400 templateName or origin missing.
406 (c: 601) Save token not found.

Register External Production (v2)

POSThttps://api.printess.com/production/v2/externaluser

Register an external order and get the design’s evaluated form field values and image data.

The improved version of /production/external, for save tokens only. It evaluates the design — resolving defaults, conditions and expressions — and returns the effective form field values plus image exchange data (the buyer’s placed images with URLs and dimensions).

Typical use: your fulfillment produces the product itself but needs the customer’s choices (size, color, name, uploaded photos) in machine-readable form.

Request Body

PropertyDescription
saveTokenrequired
string
The save token of the design (st:...).
originrequired
string
Free text tag for searching your orders.
externalOrderIdrequired
string
Your shop's order id.
productType
string
Free text product type.
orderMetaData
string
Meta data stored with the order (string; serialize JSON yourself).

Try It Live

Requests are sent to https://api.printess.com/production/v2/external with your Service Token.

Code Example

Ready-to-use code with the minimal payload. Replace YOUR_PRINTESS_SERVICE_TOKEN with your Service Token.

// Register an external order and get the design's evaluated form field values and image data.
const response = await fetch("https://api.printess.com/production/v2/external", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "saveToken": "st:YOUR_SAVE_TOKEN",
    "origin": "your-shop.com",
    "externalOrderId": "YOUR_ORDER_ID"
  })
});

if (!response.ok) {
  throw new Error("Printess API error " + response.status + ": " + await response.text());
}

const result = await response.json();
console.log(result);
curl -X POST "https://api.printess.com/production/v2/external" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "saveToken": "st:YOUR_SAVE_TOKEN",
  "origin": "your-shop.com",
  "externalOrderId": "YOUR_ORDER_ID"
}'
// Register an external order and get the design's evaluated form field values and image data.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""saveToken"": ""st:YOUR_SAVE_TOKEN"",
  ""origin"": ""your-shop.com"",
  ""externalOrderId"": ""YOUR_ORDER_ID""
}";

using (var client = new HttpClient())
{
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_PRINTESS_SERVICE_TOKEN");

    var content = new StringContent(payload, Encoding.UTF8, "application/json");
    var response = await client.PostAsync("https://api.printess.com/production/v2/external", content);

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException("Printess API error " + (int)response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }

    var result = await response.Content.ReadAsStringAsync();
    Console.WriteLine(result);
}
<?php
// Register an external order and get the design's evaluated form field values and image data.
$payload = [
    'saveToken' => 'st:YOUR_SAVE_TOKEN',
    'origin' => 'your-shop.com',
    'externalOrderId' => 'YOUR_ORDER_ID',
];

$ch = curl_init('https://api.printess.com/production/v2/external');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException("Printess API error $status: $response");
}

$result = json_decode($response, true);
print_r($result);

Response

PropertyDescription
orderId
string
Id of the registered order.
data
object
The evaluated design data.
3 nested properties
environment
map<string, string>
The design's form field values, evaluated — name to value. Includes system fields like COLOR_SCHEME and DOCUMENT_SIZE when present.
environmentDetailed
map<string, object>
The same fields with details: {value, label, info, maxCharacters} — for select-list fields the matched entry with its label.
exchangeIds
map<string, object>
For every image frame with an exchange id: {type: "image", images: [{url, width, height}]} with the available resolutions sorted small to large — the buyer's placed images.

Errors

Status / Code Meaning
400 saveToken, origin or externalOrderId missing.
406 (c: 601) Save token not found.
500 The design could not be evaluated — the message contains the error.

Schemas

Copy-ready type definitions for the object types of this endpoint. All their properties are also listed in the tables above.

data response
interface Data {
  environment?: Record<string, string>;
  environmentDetailed?: Record<string, object>;
  exchangeIds?: Record<string, object>;
}
public class Data
{
    [JsonPropertyName("environment")]
    public Dictionary<string, string> Environment { get; set; }

    [JsonPropertyName("environmentDetailed")]
    public Dictionary<string, object> EnvironmentDetailed { get; set; }

    [JsonPropertyName("exchangeIds")]
    public Dictionary<string, object> ExchangeIds { get; set; }
}
<?php

class Data
{
    /** @var array<string, string>|null */
    public ?array $environment = null;
    /** @var array<string, object>|null */
    public ?array $environmentDetailed = null;
    /** @var array<string, object>|null */
    public ?array $exchangeIds = null;
}

Retry Order

POSThttps://api.printess.com/order/retryuser

Re-run an existing production order under a new job id.

Re-enqueues an existing order for production. A new order (with new jobId and orderId) is created; the original stays untouched. Use it after a transient failure or after fixing print settings.

Caveats: orders older than 30 days are retried without their original variable data (it has been cleaned up by then) — they render with template defaults. Orders created by the editor itself (not via the production API) cannot be retried.

Request Body

PropertyDescription
orderIdrequired
string
The order to retry (from /orders/list or a produce response).
origin
string
Optionally set a new origin on the retried order — handy for tagging retries.
clearDropshipData
booleandefault: false
Remove the dropship configuration from the retried order — it renders the files but performs no dropshipping.
reloadPaymentData
booleandefault: false
Ask the system to reload payment data for the current user.

Try It Live

Requests are sent to https://api.printess.com/order/retry with your Service Token.

Code Example

Ready-to-use code with the minimal payload. Replace YOUR_PRINTESS_SERVICE_TOKEN with your Service Token.

// Re-run an existing production order under a new job id.
const response = await fetch("https://api.printess.com/order/retry", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "orderId": "YOUR_ORDER_ID"
  })
});

if (!response.ok) {
  throw new Error("Printess API error " + response.status + ": " + await response.text());
}

const result = await response.json();
console.log(result);
curl -X POST "https://api.printess.com/order/retry" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "orderId": "YOUR_ORDER_ID"
}'
// Re-run an existing production order under a new job id.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""orderId"": ""YOUR_ORDER_ID""
}";

using (var client = new HttpClient())
{
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_PRINTESS_SERVICE_TOKEN");

    var content = new StringContent(payload, Encoding.UTF8, "application/json");
    var response = await client.PostAsync("https://api.printess.com/order/retry", content);

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException("Printess API error " + (int)response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }

    var result = await response.Content.ReadAsStringAsync();
    Console.WriteLine(result);
}
<?php
// Re-run an existing production order under a new job id.
$payload = [
    'orderId' => 'YOUR_ORDER_ID',
];

$ch = curl_init('https://api.printess.com/order/retry');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException("Printess API error $status: $response");
}

$result = json_decode($response, true);
print_r($result);

Response

PropertyDescription
jobId
string
The NEW job id.
orderId
string
The NEW order id.

Errors

Status / Code Meaning
404 Order not found, or it has no stored job data.
406 The order was created by the editor and cannot be retried via the API.

Get Job Status

POSThttps://api.printess.com/production/status/getshop

Poll the full status and result of a production job.

Returns the current status of a render job. Poll until isFinalStatus is true, then check isSuccess: on success result.r maps each document name to its file URL (for image/movie output the files are in result.p instead); on failure errorDetails tells you what went wrong.

Note: an unknown jobId does not produce an error — it returns a status with isFinalStatus: false and empty timestamps. Status information is kept for 30 days.

Request Body

PropertyDescription
jobIdrequired
string
The job id returned by a produce call.

Try It Live

Requests are sent to https://api.printess.com/production/status/get with your Service Token.

Code Example

Ready-to-use code with the minimal payload. Replace YOUR_PRINTESS_SERVICE_TOKEN with your Service Token.

// Poll the full status and result of a production job.
const response = await fetch("https://api.printess.com/production/status/get", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "jobId": "YOUR_JOB_ID"
  })
});

if (!response.ok) {
  throw new Error("Printess API error " + response.status + ": " + await response.text());
}

const result = await response.json();
console.log(result);
curl -X POST "https://api.printess.com/production/status/get" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "jobId": "YOUR_JOB_ID"
}'
// Poll the full status and result of a production job.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""jobId"": ""YOUR_JOB_ID""
}";

using (var client = new HttpClient())
{
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_PRINTESS_SERVICE_TOKEN");

    var content = new StringContent(payload, Encoding.UTF8, "application/json");
    var response = await client.PostAsync("https://api.printess.com/production/status/get", content);

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException("Printess API error " + (int)response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }

    var result = await response.Content.ReadAsStringAsync();
    Console.WriteLine(result);
}
<?php
// Poll the full status and result of a production job.
$payload = [
    'jobId' => 'YOUR_JOB_ID',
];

$ch = curl_init('https://api.printess.com/production/status/get');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException("Printess API error $status: $response");
}

$result = json_decode($response, true);
print_r($result);

Response

PropertyDescription
jobId
string
The queried job id.
isFinalStatus
boolean
true once the job finished (successfully or not) — stop polling then.
isSuccess
boolean
true when the job produced successfully.
enqueuedOn
string (date-time)
When the job was queued.
processingOn
string (date-time)
When rendering started.
finishedOn
string (date-time)
When the job finished successfully.
failedOn
string (date-time)
When the job failed.
errorDetails
string
Error description when the job failed.
templateName
string
The produced template.
result
ProcessResults
The production result — only populated once the job finished.
6 nested properties
r
map<string, string>
Document name to output file URL — the main result for PDF output.
p
{d, u, i}[]
Output files for png/jpg (one per page) and gif/movie: d = document name, u = URL, i = page index.
ff
string
URL of a JSON file with the evaluated form field values of the design.
oi
object
Output information: pageCounts (pages per document), hasInvalidGlyph (a character had no glyph in the chosen font — quality warning), outputWidth/outputHeight and animationSeconds for movie output.
ayx
object
Atomyx post-processing result when atomyxProfile was used: s = failed, e = error message, r = document name to processed file URL.
s
object
Render statistics (preparation / processing / conversion / distribution times in milliseconds).

Errors

Status / Code Meaning
400 jobId missing.

Schemas

Copy-ready type definitions for the object types of this endpoint. All their properties are also listed in the tables above.

ProcessResults response
interface ProcessResults {
  r?: Record<string, string>;
  p?: object[];
  ff?: string;
  oi?: object;
  ayx?: object;
  s?: object;
}
public class ProcessResults
{
    [JsonPropertyName("r")]
    public Dictionary<string, string> R { get; set; }

    [JsonPropertyName("p")]
    public List<object> P { get; set; }

    [JsonPropertyName("ff")]
    public string Ff { get; set; }

    [JsonPropertyName("oi")]
    public object Oi { get; set; }

    [JsonPropertyName("ayx")]
    public object Ayx { get; set; }

    [JsonPropertyName("s")]
    public object S { get; set; }
}
<?php

class ProcessResults
{
    /** @var array<string, string>|null */
    public ?array $r = null;
    /** @var mixed[]|null */
    public ?array $p = null;
    public ?string $ff = null;
    public ?object $oi = null;
    public ?object $ayx = null;
    public ?object $s = null;
}

Get Job Status (PDF)

POSThttps://api.printess.com/production/status/pdf/getshop

Simplified status: just the PDF URLs, or the error.

A flattened variant of /production/status/get for the common PDF case: once isFinalStatus is true, pdfs lists each produced document with its download URL, or isError/errorDetails describe the failure.

Note: pdfs is only filled for PDF output — for png/jpg/gif/movie jobs use /production/status/get and read result.p.

Request Body

PropertyDescription
jobIdrequired
string
The job id returned by a produce call.

Try It Live

Requests are sent to https://api.printess.com/production/status/pdf/get with your Service Token.

Code Example

Ready-to-use code with the minimal payload. Replace YOUR_PRINTESS_SERVICE_TOKEN with your Service Token.

// Simplified status: just the PDF URLs, or the error.
const response = await fetch("https://api.printess.com/production/status/pdf/get", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "jobId": "YOUR_JOB_ID"
  })
});

if (!response.ok) {
  throw new Error("Printess API error " + response.status + ": " + await response.text());
}

const result = await response.json();
console.log(result);
curl -X POST "https://api.printess.com/production/status/pdf/get" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "jobId": "YOUR_JOB_ID"
}'
// Simplified status: just the PDF URLs, or the error.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""jobId"": ""YOUR_JOB_ID""
}";

using (var client = new HttpClient())
{
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_PRINTESS_SERVICE_TOKEN");

    var content = new StringContent(payload, Encoding.UTF8, "application/json");
    var response = await client.PostAsync("https://api.printess.com/production/status/pdf/get", content);

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException("Printess API error " + (int)response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }

    var result = await response.Content.ReadAsStringAsync();
    Console.WriteLine(result);
}
<?php
// Simplified status: just the PDF URLs, or the error.
$payload = [
    'jobId' => 'YOUR_JOB_ID',
];

$ch = curl_init('https://api.printess.com/production/status/pdf/get');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException("Printess API error $status: $response");
}

$result = json_decode($response, true);
print_r($result);

Response

PropertyDescription
isFinalStatus
boolean
true once the job finished — stop polling then.
isError
boolean
true when the job failed.
errorDetails
string
Error description when the job failed.
formFieldsUrl
string
URL of a JSON file with the evaluated form field values.
pdfs
{documentName, url}[]
The produced PDF files: document name and download URL.

Errors

Status / Code Meaning
400 jobId missing.

Download Order Files as Zip

POSThttps://api.printess.com/production/orders/files/zipuser

Bundle the output files of one or more orders into a single zip download.

Collects all output files of the given orders into one zip archive and returns its download URL. Inside the archive, each order’s files live in their own folder.

With infoJson you can name those folders by template (instead of the order id) and embed an info.json into the archive.

Request Body

PropertyDescription
orderIdsrequired
string[]
The orders whose files to bundle (from /orders/list).
infoJson
string
Optional serialized JSON of the shape {"<orderId>": {"templateName": "<folder name>"}} — names the per-order folders in the archive. The string is also stored as info.json inside the zip.

Try It Live

Requests are sent to https://api.printess.com/production/orders/files/zip with your Service Token.

Code Example

Ready-to-use code with the minimal payload. Replace YOUR_PRINTESS_SERVICE_TOKEN with your Service Token.

// Bundle the output files of one or more orders into a single zip download.
const response = await fetch("https://api.printess.com/production/orders/files/zip", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "orderIds": [
      "YOUR_ORDER_ID"
    ]
  })
});

if (!response.ok) {
  throw new Error("Printess API error " + response.status + ": " + await response.text());
}

const result = await response.json();
console.log(result);
curl -X POST "https://api.printess.com/production/orders/files/zip" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "orderIds": [
    "YOUR_ORDER_ID"
  ]
}'
// Bundle the output files of one or more orders into a single zip download.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""orderIds"": [
    ""YOUR_ORDER_ID""
  ]
}";

using (var client = new HttpClient())
{
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_PRINTESS_SERVICE_TOKEN");

    var content = new StringContent(payload, Encoding.UTF8, "application/json");
    var response = await client.PostAsync("https://api.printess.com/production/orders/files/zip", content);

    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException("Printess API error " + (int)response.StatusCode + ": " + await response.Content.ReadAsStringAsync());
    }

    var result = await response.Content.ReadAsStringAsync();
    Console.WriteLine(result);
}
<?php
// Bundle the output files of one or more orders into a single zip download.
$payload = [
    'orderIds' => [
        'YOUR_ORDER_ID',
    ],
];

$ch = curl_init('https://api.printess.com/production/orders/files/zip');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException("Printess API error $status: $response");
}

$result = json_decode($response, true);
print_r($result);

Response

PropertyDescription
url
string
Download URL of the created zip archive.

Errors

Status / Code Meaning
400 / 406 (c: 101) orderIds missing or empty.
404 None of the orders were found, or none of them have output files.