Orders Endpoints

Query the print jobs (orders) you started: order history, output file URLs, and filter helpers for building order screens. 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.

List Orders

POSThttps://api.printess.com/orders/listuser

Search your production orders and read their state and output file URLs.

The order history and lookup endpoint. Typical uses for a shop integration: find the production order that belongs to a shop order (filter by externalOrderId), find the order behind a cart item (filter by saveToken), check whether production finished (isFinished / isFailure) and read the produced file URLs from result.

All filters are optional and combined with AND. Results are ordered by creation date, newest first.

Request Body

Property	Description
`externalOrderId` `string`	Exact match on the external order id you passed when producing — the easiest way to find the orders of one shop order.
`saveToken` `string`	Exact match on the save token the order was produced from. Maps a cart item directly to its production order.
`templateName` `string`	Filter by template name, combined with `templateNameOperator`.
`templateNameOperator` `string`default: `Contains`	How `templateName` is matched. `Contains` and `StartsWith` match case-insensitively; `Equals` is case-sensitive. Values: `Contains` `StartsWith` `Equals`
`origin` `string`	Exact match on the origin tag you passed when producing.
`productType` `string`	Exact match on the product type you passed when producing.
`startDate` `string (date-time)`	Only orders created on or after this date.
`endDate` `string (date-time)`	Only orders created on or before this date.
`isFinished` `boolean`	Filter by whether production has completed.
`isFailed` `boolean`	Filter by whether production failed.
`isImposed` `boolean`	Filter by whether an imposition was used for at least one output file.
`hasExternalOrderId` `boolean`	`true` = only orders that carry an external order id, `false` = only orders without one.
`take` `integer`default: `100`	Page size, maximum 500.
`skip` `integer`default: `0`	Number of entries to skip (paging).
`onlyMyOrders` `boolean`	Only relevant when your account is pinned to a parent account: `true` restricts the result to orders your own account created.

Try It Live

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

Code Example

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

// Search your production orders and read their state and output file URLs.
const response = await fetch("https://api.printess.com/orders/list", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "externalOrderId": "YOUR_SHOP_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/orders/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "externalOrderId": "YOUR_SHOP_ORDER_ID"
}'

// Search your production orders and read their state and output file URLs.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""externalOrderId"": ""YOUR_SHOP_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/orders/list", 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
// Search your production orders and read their state and output file URLs.
$payload = [
    'externalOrderId' => 'YOUR_SHOP_ORDER_ID',
];

$ch = curl_init('https://api.printess.com/orders/list');
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

Returns the matching orders, a user lookup table and the total count.

Property Description

orders

Order[]

The matching orders, newest first.

21 nested properties

`id` `string`	Id of this order — use it for `/order/retry` or `/production/orders/files/zip`.
`jobId` `string`	The render job id — use it with `/production/status/get`.
`externalOrderId` `string`	The external order id you passed when producing.
`templateName` `string`	The source template of this order (may carry a `~published` suffix when the published version was produced).
`origin` `string`	The origin tag set when creating this order.
`shopSaveId` `string`	The save token this order was produced from (if any).
`loadableTemplateName` `string`	The name to load in the Printess editor to see the exact design that was produced — the save token for shop orders, otherwise the plain template name.
`productType` `string`	The product type set for this order.
`createdOn` `string (date-time)`	Creation time (UTC).
`finishedOn` `string (date-time)`	Completion time (UTC), `null` while still producing.
`isFinished` `boolean`	Production completed (successfully or not).
`isFailure` `boolean`	Production failed — see `failureDetails`.
`failureDetails` `string`	Error details when the order failed.
`result` `ProcessResults`	The production result. `result.d` maps each document name to its output file URL; `result.zip` is a zip of all files; `result.ff` points to the form field values used. `null` until the order has produced.
`documents` `integer`	Number of documents produced.
`copies` `integer`	Number of copies.
`pages` `integer`	Number of pages produced.
`size` `integer (int64)`	Combined size of all output files in bytes.
`usedCredits` `number`	Credits charged for this order.
`metaData` `string`	The `orderMetaData` you sent in the produce call.
`usedPublishedVersion` `boolean`	Whether the published version of the template was produced.

users

UserInfo[]

Lookup table for the user ids appearing in the orders: {id, d: display name, e: email}.

count

integer

Total number of matching orders (ignoring paging).

Errors

Status / Code	Meaning
`401`	Missing or invalid token.

Schemas

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

Order response

interface Order {
  id?: string;
  jobId?: string;
  externalOrderId?: string;
  templateName?: string;
  origin?: string;
  shopSaveId?: string;
  loadableTemplateName?: string;
  productType?: string;
  createdOn?: string;
  finishedOn?: string;
  isFinished?: boolean;
  isFailure?: boolean;
  failureDetails?: string;
  result?: ProcessResults;
  documents?: number;
  copies?: number;
  pages?: number;
  size?: number;
  usedCredits?: number;
  metaData?: string;
  usedPublishedVersion?: boolean;
}

public class Order
{
    [JsonPropertyName("id")]
    public string Id { get; set; }

    [JsonPropertyName("jobId")]
    public string JobId { get; set; }

    [JsonPropertyName("externalOrderId")]
    public string ExternalOrderId { get; set; }

    [JsonPropertyName("templateName")]
    public string TemplateName { get; set; }

    [JsonPropertyName("origin")]
    public string Origin { get; set; }

    [JsonPropertyName("shopSaveId")]
    public string ShopSaveId { get; set; }

    [JsonPropertyName("loadableTemplateName")]
    public string LoadableTemplateName { get; set; }

    [JsonPropertyName("productType")]
    public string ProductType { get; set; }

    [JsonPropertyName("createdOn")]
    public DateTime? CreatedOn { get; set; }

    [JsonPropertyName("finishedOn")]
    public DateTime? FinishedOn { get; set; }

    [JsonPropertyName("isFinished")]
    public bool? IsFinished { get; set; }

    [JsonPropertyName("isFailure")]
    public bool? IsFailure { get; set; }

    [JsonPropertyName("failureDetails")]
    public string FailureDetails { get; set; }

    [JsonPropertyName("result")]
    public ProcessResults Result { get; set; }

    [JsonPropertyName("documents")]
    public int? Documents { get; set; }

    [JsonPropertyName("copies")]
    public int? Copies { get; set; }

    [JsonPropertyName("pages")]
    public int? Pages { get; set; }

    [JsonPropertyName("size")]
    public long? Size { get; set; }

    [JsonPropertyName("usedCredits")]
    public double? UsedCredits { get; set; }

    [JsonPropertyName("metaData")]
    public string MetaData { get; set; }

    [JsonPropertyName("usedPublishedVersion")]
    public bool? UsedPublishedVersion { get; set; }
}

<?php

class Order
{
    public ?string $id = null;
    public ?string $jobId = null;
    public ?string $externalOrderId = null;
    public ?string $templateName = null;
    public ?string $origin = null;
    public ?string $shopSaveId = null;
    public ?string $loadableTemplateName = null;
    public ?string $productType = null;
    public ?string $createdOn = null;
    public ?string $finishedOn = null;
    public ?bool $isFinished = null;
    public ?bool $isFailure = null;
    public ?string $failureDetails = null;
    public ?ProcessResults $result = null;
    public ?int $documents = null;
    public ?int $copies = null;
    public ?int $pages = null;
    public ?int $size = null;
    public ?float $usedCredits = null;
    public ?string $metaData = null;
    public ?bool $usedPublishedVersion = null;
}

Unique Order Template Names

POSThttps://api.printess.com/orders/templates/uniqueuser

Distinct template names across your orders — for filter dropdowns.

Returns the distinct template names that appear in your orders, optionally restricted to one origin and/or product type. Use it to populate a template filter dropdown in an order history screen without paging through all orders.

Request Body

Property	Description
`origin` `string`	Only consider orders with this exact origin.
`productType` `string`	Only consider orders with this exact product type.

Try It Live

Requests are sent to https://api.printess.com/orders/templates/unique with your Service Token.

Code Example

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

// Distinct template names across your orders — for filter dropdowns.
const response = await fetch("https://api.printess.com/orders/templates/unique", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({})
});

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/orders/templates/unique" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{}'

// Distinct template names across your orders — for filter dropdowns.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{}";

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/orders/templates/unique", 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
// Distinct template names across your orders — for filter dropdowns.
$payload = (object) [];

$ch = curl_init('https://api.printess.com/orders/templates/unique');
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

Property	Description
`templateNames` `string[]`	Sorted list of distinct template names.

Errors

Status / Code	Meaning
`401`	Missing or invalid token.

Unique Order Origins

POSThttps://api.printess.com/orders/origins/uniqueuser

Distinct origin tags across your orders — for filter dropdowns.

Returns the distinct origin tags that appear in your orders. Use it to discover which origin values your integration has been sending and to populate an origin filter dropdown.

This endpoint takes no parameters — send an empty JSON object.

Request Body

This endpoint needs no request body. Send an empty JSON object {}.

Try It Live

Requests are sent to https://api.printess.com/orders/origins/unique with your Service Token.

Code Example

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

// Distinct origin tags across your orders — for filter dropdowns.
const response = await fetch("https://api.printess.com/orders/origins/unique", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({})
});

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/orders/origins/unique" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{}'

// Distinct origin tags across your orders — for filter dropdowns.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{}";

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/orders/origins/unique", 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
// Distinct origin tags across your orders — for filter dropdowns.
$payload = (object) [];

$ch = curl_init('https://api.printess.com/orders/origins/unique');
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

Property	Description
`origins` `string[]`	Sorted list of distinct origins. May include internal origins like `template/save`.

Errors

Status / Code	Meaning
`401`	Missing or invalid token.

List Submission Errors

POSThttps://api.printess.com/submission/errors/listuser

Rejected produce requests — see what your integration sent and why it failed.

Returns produce submissions that were rejected or failed with an error, including the raw JSON your integration sent. Very useful while developing: if a /dropship/produce or /production/produce call fails, the exact payload and the error are recorded here.

Request Body

Property	Description
`startDate` `string (date-time)`	Only errors on or after this date.
`endDate` `string (date-time)`	Only errors on or before this date.
`take` `integer`default: `100`	Page size, maximum 500.
`skip` `integer`default: `0`	Number of entries to skip (paging).
`userId` `string`	Admin only — ignored for regular accounts.

Try It Live

Requests are sent to https://api.printess.com/submission/errors/list with your Service Token.

Code Example

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

// Rejected produce requests — see what your integration sent and why it failed.
const response = await fetch("https://api.printess.com/submission/errors/list", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({})
});

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/submission/errors/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{}'

// Rejected produce requests — see what your integration sent and why it failed.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{}";

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/submission/errors/list", 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
// Rejected produce requests — see what your integration sent and why it failed.
$payload = (object) [];

$ch = curl_init('https://api.printess.com/submission/errors/list');
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

Returns the recorded submission errors with the payload that was sent and the error message.

Errors

Status / Code	Meaning
`401`	Missing or invalid token.