Templates and Directories Endpoints

List and inspect the templates of your account, read their form fields (the buyer-facing product options), check template existence and turn saved buyer designs into templates. 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 Template Form Fields

POSThttps://api.printess.com/template/formFields/listuser

Read the product options (form fields) of a template — the schema for your product page UI.

Form fields are the buyer inputs of a template: every option the customer can choose or type (a size dropdown, a name text field, a color selection). This endpoint returns their full schema — names, labels, allowed values, defaults, whether they affect the price and whether they are mandatory — so your storefront can render matching option controls and map them to shop variants.

The name of a form field and the key of its entries are exactly the values you later pass as formFields to the mockup endpoints and as vdp.form to the produce endpoints.

Note: save tokens are not accepted here — pass a real template name.

Request Body

Property	Description
`templateName`required `string`	The template to read the form fields from. Must be a template name — save tokens (`st:...`) are rejected.
`usePublishedVersion` `boolean`default: `false`	Read from the published version of the template. If no published version exists, the draft version is returned instead (without an error).

Try It Live

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

Code Example

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

// Read the product options (form fields) of a template — the schema for your product page UI.
const response = await fetch("https://api.printess.com/template/formFields/list", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "templateName": "YOUR_TEMPLATE_NAME"
  })
});

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

// Read the product options (form fields) of a template — the schema for your product page UI.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

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

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/template/formFields/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
// Read the product options (form fields) of a template — the schema for your product page UI.
$payload = [
    'templateName' => 'YOUR_TEMPLATE_NAME',
];

$ch = curl_init('https://api.printess.com/template/formFields/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

Property Description

colorScheme

string

The template's color scheme, if one is set.

formFields

FormField[]

The template-level (global) form fields — the main product options.

12 nested properties

name

string

The identifier of the form field. This is the key you send in formFields (mockups) or vdp.form (production).

display

string

Human-readable caption for your UI label.

groupName

string

Group name for laying out related options together.

value

string

The default value.

info

string

Help / tooltip text.

isPriceRelevant

boolean

This option changes the product price — map it to a shop variant or price modifier.

isMandatory

boolean

The buyer must provide a value.

dataType

string

Data type of the value (e.g. text, number, boolean).

userInterface

string

Suggested UI control (dropdown, text box, color picker, ...).

maximumCharacters

integer

Maximum length for free-text fields; 0 = unlimited.

visibility

string

Visibility rule of the field.

entries

FormFieldEntry[]

The allowed values. Empty for free-text fields.

3 nested properties

`key` `string`	The unique key of this entry — the literal value you send back when setting the form field.
`label` `string`	Display label for the entry.
`description` `string`	Longer description of the entry.

documentFormFields

DocumentFormFields[]

Per-document form fields: {documentId, documentName, formFields} with the same form field structure as above.

Errors

Status / Code	Meaning
`406 (c: 1)`	`templateName` empty, or the template has no content.
`403`	A save token was passed as `templateName`.

Schemas

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

FormField response

interface FormField {
  name?: string;
  display?: string;
  groupName?: string;
  value?: string;
  info?: string;
  isPriceRelevant?: boolean;
  isMandatory?: boolean;
  dataType?: string;
  userInterface?: string;
  maximumCharacters?: number;
  visibility?: string;
  entries?: FormFieldEntry[];
}

public class FormField
{
    [JsonPropertyName("name")]
    public string Name { get; set; }

    [JsonPropertyName("display")]
    public string Display { get; set; }

    [JsonPropertyName("groupName")]
    public string GroupName { get; set; }

    [JsonPropertyName("value")]
    public string Value { get; set; }

    [JsonPropertyName("info")]
    public string Info { get; set; }

    [JsonPropertyName("isPriceRelevant")]
    public bool? IsPriceRelevant { get; set; }

    [JsonPropertyName("isMandatory")]
    public bool? IsMandatory { get; set; }

    [JsonPropertyName("dataType")]
    public string DataType { get; set; }

    [JsonPropertyName("userInterface")]
    public string UserInterface { get; set; }

    [JsonPropertyName("maximumCharacters")]
    public int? MaximumCharacters { get; set; }

    [JsonPropertyName("visibility")]
    public string Visibility { get; set; }

    [JsonPropertyName("entries")]
    public List<FormFieldEntry> Entries { get; set; }
}

<?php

class FormField
{
    public ?string $name = null;
    public ?string $display = null;
    public ?string $groupName = null;
    public ?string $value = null;
    public ?string $info = null;
    public ?bool $isPriceRelevant = null;
    public ?bool $isMandatory = null;
    public ?string $dataType = null;
    public ?string $userInterface = null;
    public ?int $maximumCharacters = null;
    public ?string $visibility = null;
    /** @var FormFieldEntry[]|null */
    public ?array $entries = null;
}

FormFieldEntry response

interface FormFieldEntry {
  key?: string;
  label?: string;
  description?: string;
}

public class FormFieldEntry
{
    [JsonPropertyName("key")]
    public string Key { get; set; }

    [JsonPropertyName("label")]
    public string Label { get; set; }

    [JsonPropertyName("description")]
    public string Description { get; set; }
}

<?php

class FormFieldEntry
{
    public ?string $key = null;
    public ?string $label = null;
    public ?string $description = null;
}

Load My Templates

POSThttps://api.printess.com/templates/user/loadexternalDesigner

List the templates of your account, filterable by folder, name and type.

The main template listing call. Returns all templates of your account, optionally restricted to one directory (folder), filtered by a name substring, a template type, or to published templates only.

Request Body

Property	Description
`directoryId` `integer`default: `0`	Restrict the result to one directory (see `/directories/load`). `0` returns templates from all directories.
`templateName` `string`	Case-insensitive substring filter on the template name.
`type` `string`	Exact match on the template type.
`publishedOnly` `boolean`default: `false`	Only return templates that have a published version.

Try It Live

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

Code Example

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

// List the templates of your account, filterable by folder, name and type.
const response = await fetch("https://api.printess.com/templates/user/load", {
  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/templates/user/load" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{}'

// List the templates of your account, filterable by folder, name and type.
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/templates/user/load", 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
// List the templates of your account, filterable by folder, name and type.
$payload = (object) [];

$ch = curl_init('https://api.printess.com/templates/user/load');
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 {uid, e, ts} where ts is the template list. Template properties use short names:

Property Description

ts

Template[]

The templates.

15 nested properties

`id` `integer`	Template id.
`n` `string`	Template name.
`turl` `string`	Thumbnail URL.
`bg` `string`	Thumbnail background color.
`w` `boolean`	Whether you may edit this template.
`p` `boolean`	Whether you may publish this template.
`d` `boolean`	Whether you may delete this template.
`hpv` `boolean`	Has a published version.
`hdv` `boolean`	Has a draft (design) version.
`ls` `string (date-time)`	Last saved.
`lp` `string (date-time)`	Last published.
`directoryId` `integer`	The directory the template lives in.
`tt` `string`	Template type.
`baseTemplate` `string`	Name of the base template this template is connected to. `null` when there is none. `/production/produce` merges the two automatically when `autoMerge` is set.
`meta` `string`	Free-form meta data string.

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.

Template response

interface Template {
  id?: number;
  n?: string;
  turl?: string;
  bg?: string;
  w?: boolean;
  p?: boolean;
  d?: boolean;
  hpv?: boolean;
  hdv?: boolean;
  ls?: string;
  lp?: string;
  directoryId?: number;
  tt?: string;
  baseTemplate?: string;
  meta?: string;
}

public class Template
{
    [JsonPropertyName("id")]
    public int? Id { get; set; }

    [JsonPropertyName("n")]
    public string N { get; set; }

    [JsonPropertyName("turl")]
    public string Turl { get; set; }

    [JsonPropertyName("bg")]
    public string Bg { get; set; }

    [JsonPropertyName("w")]
    public bool? W { get; set; }

    [JsonPropertyName("p")]
    public bool? P { get; set; }

    [JsonPropertyName("d")]
    public bool? D { get; set; }

    [JsonPropertyName("hpv")]
    public bool? Hpv { get; set; }

    [JsonPropertyName("hdv")]
    public bool? Hdv { get; set; }

    [JsonPropertyName("ls")]
    public DateTime? Ls { get; set; }

    [JsonPropertyName("lp")]
    public DateTime? Lp { get; set; }

    [JsonPropertyName("directoryId")]
    public int? DirectoryId { get; set; }

    [JsonPropertyName("tt")]
    public string Tt { get; set; }

    [JsonPropertyName("baseTemplate")]
    public string BaseTemplate { get; set; }

    [JsonPropertyName("meta")]
    public string Meta { get; set; }
}

<?php

class Template
{
    public ?int $id = null;
    public ?string $n = null;
    public ?string $turl = null;
    public ?string $bg = null;
    public ?bool $w = null;
    public ?bool $p = null;
    public ?bool $d = null;
    public ?bool $hpv = null;
    public ?bool $hdv = null;
    public ?string $ls = null;
    public ?string $lp = null;
    public ?int $directoryId = null;
    public ?string $tt = null;
    public ?string $baseTemplate = null;
    public ?string $meta = null;
}

Load Recent Templates

POSThttps://api.printess.com/templates/user/recent/loadexternalDesigner

Your most recently edited templates.

Returns your templates ordered by last save date, newest first — for a “recently edited” strip on a dashboard.

Always send an explicit count: sending an empty object returns an empty list.

Request Body

Property	Description
`count`required `integer`	How many templates to return. Sending `0` (or an empty body object) returns an empty list.

Try It Live

Requests are sent to https://api.printess.com/templates/user/recent/load with your Service Token.

Code Example

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

// Your most recently edited templates.
const response = await fetch("https://api.printess.com/templates/user/recent/load", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "count": 20
  })
});

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/templates/user/recent/load" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "count": 20
}'

// Your most recently edited templates.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""count"": 20
}";

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/templates/user/recent/load", 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
// Your most recently edited templates.
$payload = [
    'count' => 20,
];

$ch = curl_init('https://api.printess.com/templates/user/recent/load');
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 {uid, e, ts} — the same template structure as /templates/user/load.

Errors

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

Load New Section Templates

POSThttps://api.printess.com/templates/user/new/loadexternalDesigner

Published templates curated as starting points for new designs.

Returns every published template that lives in (or below) a top-level folder literally named NEW-SECTION. Create that folder in the template browser, move templates into it and publish them — they then appear here as read-only starting points for the editor’s “New” gallery.

This endpoint takes no parameters — send an empty JSON object. If the folder does not exist, the list is empty.

Request Body

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

Try It Live

Requests are sent to https://api.printess.com/templates/user/new/load with your Service Token.

Code Example

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

// Published templates curated as starting points for new designs.
const response = await fetch("https://api.printess.com/templates/user/new/load", {
  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/templates/user/new/load" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{}'

// Published templates curated as starting points for new designs.
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/templates/user/new/load", 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
// Published templates curated as starting points for new designs.
$payload = (object) [];

$ch = curl_init('https://api.printess.com/templates/user/new/load');
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 {uid, ts} — the same template structure as /templates/user/load, all entries read-only.

Errors

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

Load Shared Templates

POSThttps://api.printess.com/templates/user/shared/loaduser

Templates another account shared with you.

Lists the templates of another account that were shared with yours (e.g. agency and client accounts, or a parent account you are pinned to). The returned write/publish/delete flags reflect your actual rights on that account’s templates.

Request Body

Property	Description
`userId`required `string`	The id of the account whose shared templates you want to list.
`directoryId` `integer`default: `0`	Restrict to one directory of that account. `0` = all.

Try It Live

Requests are sent to https://api.printess.com/templates/user/shared/load with your Service Token.

Code Example

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

// Templates another account shared with you.
const response = await fetch("https://api.printess.com/templates/user/shared/load", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "userId": "OTHER_USER_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/templates/user/shared/load" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "userId": "OTHER_USER_ID"
}'

// Templates another account shared with you.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""userId"": ""OTHER_USER_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/templates/user/shared/load", 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
// Templates another account shared with you.
$payload = [
    'userId' => 'OTHER_USER_ID',
];

$ch = curl_init('https://api.printess.com/templates/user/shared/load');
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 {uid, e, ts} — the same template structure as /templates/user/load, with w/p/d reflecting your effective rights.

Errors

Status / Code	Meaning
`400`	`userId` missing.
`403`	That account has not shared its templates with you.

List All Visible Templates

POSThttps://api.printess.com/templates/listexternalDesigner

Everything you can see, grouped by owning account.

One call that returns every template visible to you, grouped by the owning account: your own templates, templates from accounts that share with you, and global Printess templates. This is what fills the editor’s template browser.

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/templates/list with your Service Token.

Code Example

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

// Everything you can see, grouped by owning account.
const response = await fetch("https://api.printess.com/templates/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/templates/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{}'

// Everything you can see, grouped by owning account.
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/templates/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
// Everything you can see, grouped by owning account.
$payload = (object) [];

$ch = curl_init('https://api.printess.com/templates/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 {gid, uid, uts}: gid is the id of the global Printess account, uid your own id, and uts an array of {uid, e, ts} buckets (one per account) with the same template structure as /templates/user/load.

Errors

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

Template Exists

POSThttps://api.printess.com/template/existsexternalDesigner

Pre-flight check whether templates exist (and are published).

Checks whether one template (templateName) or several templates (templateNames) exist. With hasPublishedVersion: true, only templates with a published version count. A shop integration typically verifies at deploy time that all templates its product catalog references are present and published.

Note: when multiple names are given, the result is true only if ALL of them exist — the response does not tell you which one is missing. Check names individually if you need to know.

Request Body

Property	Description
`templateName` `string`	A single template name to check. Provide this or `templateNames`.
`templateNames` `string[]`	Multiple template names — the result is `true` only if all of them exist.
`hasPublishedVersion` `boolean`default: `false`	Require a published version for a template to count as existing.
`userId` `string`	Check inside another account that shared its templates with you. Defaults to your own account.

Try It Live

Requests are sent to https://api.printess.com/template/exists with your Service Token.

Code Example

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

// Pre-flight check whether templates exist (and are published).
const response = await fetch("https://api.printess.com/template/exists", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "templateName": "YOUR_TEMPLATE_NAME"
  })
});

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/template/exists" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "templateName": "YOUR_TEMPLATE_NAME"
}'

// Pre-flight check whether templates exist (and are published).
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

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

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/template/exists", 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
// Pre-flight check whether templates exist (and are published).
$payload = [
    'templateName' => 'YOUR_TEMPLATE_NAME',
];

$ch = curl_init('https://api.printess.com/template/exists');
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 a plain JSON boolean: true or false.

Errors

Status / Code	Meaning
`406 (c: 100)`	Neither `templateName` nor `templateNames` provided.
`403`	No read access to the requested account.

Template Details

POSThttps://api.printess.com/template/detailsany authenticated

Thumbnails, document info and pricing categories of one template.

Returns everything a back-office or product page needs about one template: per-page thumbnail images, per-document pricing categories and your effective rights on the template.

Identify the template either by templateId or by templateName (the id wins if both are set).

Request Body

Property	Description
`templateName` `string`	The template name. Used when `templateId` is not set.
`templateId` `integer`	The template id. Takes precedence over `templateName`.
`usePublishedVersion` `boolean`default: `false`	Read from the published version of the template.
`userId` `string`	Read a template of another account that shared with you. Defaults to your own account.

Try It Live

Requests are sent to https://api.printess.com/template/details with your Service Token.

Code Example

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

// Thumbnails, document info and pricing categories of one template.
const response = await fetch("https://api.printess.com/template/details", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "templateName": "YOUR_TEMPLATE_NAME"
  })
});

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/template/details" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "templateName": "YOUR_TEMPLATE_NAME"
}'

// Thumbnails, document info and pricing categories of one template.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

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

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/template/details", 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
// Thumbnails, document info and pricing categories of one template.
$payload = [
    'templateName' => 'YOUR_TEMPLATE_NAME',
];

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

id

integer

Template id.

userId

string

Owning account id.

images

TemplateImage[]

Rendered page thumbnails.

5 nested properties

`did` `string`	Document id the image belongs to.
`si` `integer`	Spread index.
`pi` `integer`	Page index.
`t` `string`	Thumbnail URL.
`bg` `string`	Background color.

documentInfo

string

Serialized JSON with additional per-document information.

documentPriceInfo

DocumentPriceInfo[]

Price categories per document: {documentName, documentId, documentPriceCategory, documentSnippetPriceCategory} — only for documents that have pricing configured.

template

Template

The template entry itself (same short-key structure as /templates/user/load).

Errors

Status / Code	Meaning
`406 (c: 602)`	Template not found.
`406 (c: 603)`	The template has no published version.
`406 (c: 403)`	No read access to the requested account’s template.

Schemas

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

TemplateImage response

interface TemplateImage {
  did?: string;
  si?: number;
  pi?: number;
  t?: string;
  bg?: string;
}

public class TemplateImage
{
    [JsonPropertyName("did")]
    public string Did { get; set; }

    [JsonPropertyName("si")]
    public int? Si { get; set; }

    [JsonPropertyName("pi")]
    public int? Pi { get; set; }

    [JsonPropertyName("t")]
    public string T { get; set; }

    [JsonPropertyName("bg")]
    public string Bg { get; set; }
}

<?php

class TemplateImage
{
    public ?string $did = null;
    public ?int $si = null;
    public ?int $pi = null;
    public ?string $t = null;
    public ?string $bg = null;
}

Create Template from Save Token

POSThttps://api.printess.com/template/from/saveTokenservice

Turn a buyer’s saved design into a reusable template in your account.

Promotes a buyer’s saved design into a normal, editable template of your account. Typical uses: a “save this design to my account” feature, turning a great customer design into a catalog product, or snapshotting a design for your design team.

The new template is created unpublished. With clearBuyerSettings: true all buyer-side settings are removed from the frames, so the result behaves like a designer-created template.

Request Body

Property	Description
`name`required `string`	The name for the new template. Must not already exist, must not be `new`, and must not contain `/` or `~`.
`saveToken`required `string`	The save token to create the template from. Must belong to your account and must not be expired.
`directoryId` `integer`default: `0`	The directory to put the new template in. `0` = root directory.
`clearBuyerSettings` `boolean`default: `false`	Remove all buyer-side settings from all frames.
`thumbnailUrl` `string`	Thumbnail URL to set for the new template. Not generated automatically — pair this with `/shop/basket/thumbnail`.

Try It Live

Requests are sent to https://api.printess.com/template/from/saveToken with your Service Token.

Code Example

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

// Turn a buyer's saved design into a reusable template in your account.
const response = await fetch("https://api.printess.com/template/from/saveToken", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "name": "Customer design 4711",
    "saveToken": "st:YOUR_SAVE_TOKEN"
  })
});

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/template/from/saveToken" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "name": "Customer design 4711",
  "saveToken": "st:YOUR_SAVE_TOKEN"
}'

// Turn a buyer's saved design into a reusable template in your account.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""name"": ""Customer design 4711"",
  ""saveToken"": ""st:YOUR_SAVE_TOKEN""
}";

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/template/from/saveToken", 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
// Turn a buyer's saved design into a reusable template in your account.
$payload = [
    'name' => 'Customer design 4711',
    'saveToken' => 'st:YOUR_SAVE_TOKEN',
];

$ch = curl_init('https://api.printess.com/template/from/saveToken');
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 created template entry (same short-key structure as /templates/user/load).

Errors

Status / Code	Meaning
`406 (c: 605)`	A template with that name already exists.
`406 (c: 606)`	`name` is empty or invalid.
`406 (c: 601)`	Save token not found in your account.
`406 (c: 202)`	Save token is expired.

Load Directory Tree

POSThttps://api.printess.com/directories/loadexternalDesigner

The complete template folder tree of your account.

Returns your entire template folder tree as one nested structure. Call it once to render a folder sidebar, then load the templates of a folder with /templates/user/load and its directoryId.

The root directory has an empty name.

Request Body

Property	Description
`userId` `string`	Load the tree of another account that shared its templates with you. Defaults to your own account.

Try It Live

Requests are sent to https://api.printess.com/directories/load with your Service Token.

Code Example

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

// The complete template folder tree of your account.
const response = await fetch("https://api.printess.com/directories/load", {
  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/directories/load" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{}'

// The complete template folder tree of your account.
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/directories/load", 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 complete template folder tree of your account.
$payload = (object) [];

$ch = curl_init('https://api.printess.com/directories/load');
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
`id` `integer`	Directory id — use it as `directoryId` in the template endpoints.
`pid` `integer`	Parent directory id (absent on the root).
`n` `string`	Directory name. The root directory's name is empty.
`m` `string`	Free-form meta data string, if set.
`c` `Directory[]`	Child directories, recursively in the same structure.

Errors

Status / Code	Meaning
`403`	No access to the requested account’s directories.

Load NEW-SECTION Directory

POSThttps://api.printess.com/directory/loadexternalDesigner

Load the special NEW-SECTION folder subtree.

Loads one top-level directory subtree by name. Currently the only accepted name is NEW-SECTION — the special folder whose published templates appear in /templates/user/new/load. For anything else use /directories/load and pick the folder from the tree.

If the folder does not exist you still get a 200 response with id: 0 — check the id, not the status code.

Request Body

Property	Description
`name`required `string`	Must be exactly `NEW-SECTION` (case-sensitive).
`userId` `string`	Load from another account that shared with you. Defaults to your own account.

Try It Live

Requests are sent to https://api.printess.com/directory/load with your Service Token.

Code Example

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

// Load the special NEW-SECTION folder subtree.
const response = await fetch("https://api.printess.com/directory/load", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "name": "NEW-SECTION"
  })
});

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/directory/load" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "name": "NEW-SECTION"
}'

// Load the special NEW-SECTION folder subtree.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""name"": ""NEW-SECTION""
}";

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/directory/load", 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
// Load the special NEW-SECTION folder subtree.
$payload = [
    'name' => 'NEW-SECTION',
];

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

The same directory structure as /directories/load. id: 0 means the folder does not exist.

Errors

Status / Code	Meaning
`406`	`name` missing or not `NEW-SECTION`.
`403`	No access to the requested account.