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.
https://api.printess.com/production/produceuserThe 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.
| Property | Description | ||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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
|
||||||||||||||||||||||||||||||||||||||||||||||||
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
|
||||||||||||||||||||||||||||||||||||||||||||||||
vdp
Vdp |
Form field values and variable data applied to the production.
4 nested properties
|
||||||||||||||||||||||||||||||||||||||||||||||||
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
|
||||||||||||||||||||||||||||||||||||||||||||||||
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. |
https://api.printess.com/production/produce with your Service Token.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.
The job was accepted and queued.
| Property | Description |
|---|---|
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.
|
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 } }
}
}
| 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. |
Copy-ready type definitions for the object types of this endpoint. All their properties are also listed in the tables above.
OutputSettings requestinterface 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 requestinterface 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 requestinterface 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 requestinterface 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;
}
https://api.printess.com/production/produce/simpleuserMinimal 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.
| Property | Description |
|---|---|
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. |
https://api.printess.com/production/produce/simple with your Service Token.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);
| Property | Description |
|---|---|
jobId
string |
Id of the queued render job — poll /production/status/get.
|
orderId
string |
Id of the created order. |
| Status / Code | Meaning |
|---|---|
406 (c: 101) |
templateName or externalOrderId missing. |
https://api.printess.com/production/savetoken/createshopCreate 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).
| Property | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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
|
||||||||||||||||||||
mergeTemplates
MergeTemplate[] |
Templates or snippets to merge into the design (same structure as in /production/produce).
10 nested properties
|
||||||||||||||||||||
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
|
https://api.printess.com/production/savetoken/create with your Service Token.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);
| Property | Description |
|---|---|
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). |
| 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. |
Copy-ready type definitions for the object types of this endpoint. All their properties are also listed in the tables above.
Action requestinterface 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 requestinterface 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 requestinterface 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;
}
https://api.printess.com/production/savetoken/create/with/formfieldsshopFast 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.
| Property | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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
|
||||||||||||||
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
|
https://api.printess.com/production/savetoken/create/with/formfields with your Service Token.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 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();
| Property | Description |
|---|---|
saveToken
string |
The created save token (st:...).
|
thumbnailUrl
string |
URL of a preview image of the design. |
| 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. |
Copy-ready type definitions for the object types of this endpoint. All their properties are also listed in the tables above.
Action requestinterface 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 requestinterface 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;
}
https://api.printess.com/production/shop/proofshopLow-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.
| Property | Description | ||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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
|
||||||||||||||||||||||||||||||||||||||||||||||||
outputSettings
OutputSettings |
Output settings — proof is forced on and the resolution is capped at 96 dpi regardless of what you send.
24 nested properties
|
https://api.printess.com/production/shop/proof with your Service Token.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);
| Property | Description |
|---|---|
jobId
string |
Id of the queued proof job — poll /production/status/pdf/get.
|
orderId
string |
Id of the created (proof) order. |
| Status / Code | Meaning |
|---|---|
406 (c: 403) |
Proof production is not enabled for this account. |
Copy-ready type definitions for the object types of this endpoint. All their properties are also listed in the tables above.
Vdp requestinterface 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 requestinterface 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;
}
https://api.printess.com/production/externaluserRegister 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.
| Property | Description |
|---|---|
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). |
https://api.printess.com/production/external with your Service Token.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);
| Property | Description |
|---|---|
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.
|
| Status / Code | Meaning |
|---|---|
400 |
templateName or origin missing. |
406 (c: 601) |
Save token not found. |
https://api.printess.com/production/v2/externaluserRegister 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.
| Property | Description |
|---|---|
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). |
https://api.printess.com/production/v2/external with your Service Token.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);
| Property | Description | ||||||
|---|---|---|---|---|---|---|---|
orderId
string |
Id of the registered order. | ||||||
data
object |
The evaluated design data.
3 nested properties
|
| 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. |
Copy-ready type definitions for the object types of this endpoint. All their properties are also listed in the tables above.
data responseinterface 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;
}
https://api.printess.com/order/retryuserRe-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.
| Property | Description |
|---|---|
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. |
https://api.printess.com/order/retry with your Service Token.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);
| Property | Description |
|---|---|
jobId
string |
The NEW job id. |
orderId
string |
The NEW order id. |
| 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. |
https://api.printess.com/production/status/getshopPoll 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.
| Property | Description |
|---|---|
jobIdrequired
string |
The job id returned by a produce call. |
https://api.printess.com/production/status/get with your Service Token.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);
| Property | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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
|
| Status / Code | Meaning |
|---|---|
400 |
jobId missing. |
Copy-ready type definitions for the object types of this endpoint. All their properties are also listed in the tables above.
ProcessResults responseinterface 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;
}
https://api.printess.com/production/status/pdf/getshopSimplified 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.
| Property | Description |
|---|---|
jobIdrequired
string |
The job id returned by a produce call. |
https://api.printess.com/production/status/pdf/get with your Service Token.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);
| Property | Description |
|---|---|
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. |
| Status / Code | Meaning |
|---|---|
400 |
jobId missing. |
https://api.printess.com/production/orders/files/zipuserBundle 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.
| Property | Description |
|---|---|
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.
|
https://api.printess.com/production/orders/files/zip with your Service Token.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);
| Property | Description |
|---|---|
url
string |
Download URL of the created zip archive. |
| 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. |