Mockups Endpoints

Generate product images (mockups) of your templates — with form field values applied, so you can render one image per variant. 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.

Create Mockup URL

POSThttps://api.printess.com/saas/mockup/url/createshop

Instantly returns a mockup image URL — rendered and cached on first access.

Builds a signed URL to the Printess mockup service. Nothing is rendered during the call, so it responds in milliseconds; the image is rendered and CDN-cached the first time the URL is fetched. This is the endpoint for anything a browser displays: product images, live variant previews (change a form field, get a new URL, swap the img src), hover thumbnails.

Default size is 1000x1000 pixels. Use formFields to render the template with specific option values — one URL per variant.

If you need an image file you can copy to your own storage instead, use /saas/mockup/url/generate.

Request Body

PropertyDescription
templateNamerequired
string
 The template to render. Note that the name is not verified during this call — an unknown template yields a URL that fails when fetched.
documentName
string
 Render a specific document of the template instead of the default one.
published
booleandefault: false
 Render the published version.
pagesToSkip
integerdefault: 0
 Skip this many pages before rendering — the way to show page 2, 3, ...
maxWidth
integerdefault: 1000
 Maximum image width in pixels.
maxHeight
integerdefault: 1000
 Maximum image height in pixels.
formFields
map<string, string>
 Form field values to apply before rendering: keys are form field names, values are entry keys (or free text) — see /template/formFields/list. Avoid form field names that collide with reserved parameters like t, w, h, d, p.
merge1
string
 Name of a template to merge into the rendered result (slots merge1 to merge3 work identically).
merge1document
string
 The document of the merge template to take.
merge1targetDocument
string
 The document of the main template to merge into.
merge2
string
 Second merge template.
merge2document
string
 Document of the second merge template.
merge2targetDocument
string
 Target document for the second merge.
merge3
string
 Third merge template.
merge3document
string
 Document of the third merge template.
merge3targetDocument
string
 Target document for the third merge.
snippetUrl
string
 URL (or snippet id) of a snippet to merge in.
snippetTargetDocumentName
string
 The document the snippet is merged into.

Try It Live

Requests are sent to https://api.printess.com/saas/mockup/url/create with your Service Token.

Code Example

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

// Instantly returns a mockup image URL — rendered and cached on first access.
const response = await fetch("https://api.printess.com/saas/mockup/url/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "templateName": "YOUR_TEMPLATE_NAME",
    "maxWidth": 600,
    "maxHeight": 600
  })
});

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/saas/mockup/url/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "templateName": "YOUR_TEMPLATE_NAME",
  "maxWidth": 600,
  "maxHeight": 600
}'

// Instantly returns a mockup image URL — rendered and cached on first access.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""templateName"": ""YOUR_TEMPLATE_NAME"",
  ""maxWidth"": 600,
  ""maxHeight"": 600
}";

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/saas/mockup/url/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
// Instantly returns a mockup image URL — rendered and cached on first access.
$payload = [
    'templateName' => 'YOUR_TEMPLATE_NAME',
    'maxWidth' => 600,
    'maxHeight' => 600,
];

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

Variant preview example (JavaScript)

Render one image per product variant by passing the form field values from /template/formFields/list.

const response = await fetch("https://api.printess.com/saas/mockup/url/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    templateName: "Mug",
    published: true,
    maxWidth: 600,
    maxHeight: 600,
    formFields: { Color: "red", Name: "Jane" }   // names/keys from /template/formFields/list
  })
});
const { url } = await response.json();
document.querySelector("#preview").src = url;   // renders on first access, cached afterwards

Response

PropertyDescription
url
string
 The mockup image URL — put it straight into an img src. The image renders on first access.
imageFrameDimensions
object
 Frame geometry information; only filled for advanced frame-property requests, otherwise empty.

Errors

Status / Code Meaning
400 templateName missing.
406 (c: 101) A snippet id was passed in snippetUrl that cannot be resolved.

Generate Mockup Image

POSThttps://api.printess.com/saas/mockup/url/generateuser

Renders a mockup now and returns the URL of the finished image file.

Synchronously renders a mockup and returns the URL of the finished PNG in Printess storage. The generated image is deleted after one day — copy it to your own storage before that. Use this when you need to own the image file, e.g. to push product images into your shop system at publish time.

Because the rendering happens during the call, expect a response time of several seconds. Each call is charged mockup credits. For browser-facing previews use the much faster /saas/mockup/url/create instead.

Always send maxWidth and maxHeight — omitting them produces a tiny image.

Request Body

PropertyDescription
templateNamerequired
string
 The template to render.
maxWidthrequired
integer
 Maximum image width in pixels (up to 1000). Always send this — omitting it produces a tiny image.
maxHeightrequired
integer
 Maximum image height in pixels (up to 1000). Always send this.
documentName
string
 Render a specific document of the template.
published
booleandefault: false
 Render the published version.
pagesToSkip
integerdefault: 0
 Skip this many pages before rendering.
formFields
map<string, string>
 Form field values to apply before rendering — see /template/formFields/list.
merge1
string
 Name of a template to merge in (slots 1-3, same as /saas/mockup/url/create).
merge1document
string
 The document of the merge template to take.
merge1targetDocument
string
 The document of the main template to merge into.
snippetUrl
string
 URL of a snippet to merge in.
snippetTargetDocumentName
string
 The document the snippet is merged into.
outputType
string
 Output format hint for the renderer (default png).

Try It Live

Requests are sent to https://api.printess.com/saas/mockup/url/generate with your Service Token.

Code Example

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

// Renders a mockup now and returns the URL of the finished image file.
const response = await fetch("https://api.printess.com/saas/mockup/url/generate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_PRINTESS_SERVICE_TOKEN"
  },
  body: JSON.stringify({
    "templateName": "YOUR_TEMPLATE_NAME",
    "maxWidth": 800,
    "maxHeight": 800
  })
});

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/saas/mockup/url/generate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRINTESS_SERVICE_TOKEN" \
  -d '{
  "templateName": "YOUR_TEMPLATE_NAME",
  "maxWidth": 800,
  "maxHeight": 800
}'

// Renders a mockup now and returns the URL of the finished image file.
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var payload = @"{
  ""templateName"": ""YOUR_TEMPLATE_NAME"",
  ""maxWidth"": 800,
  ""maxHeight"": 800
}";

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/saas/mockup/url/generate", 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
// Renders a mockup now and returns the URL of the finished image file.
$payload = [
    'templateName' => 'YOUR_TEMPLATE_NAME',
    'maxWidth' => 800,
    'maxHeight' => 800,
];

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

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

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

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

Response

PropertyDescription
url
string
 URL of the rendered image. Identical parameters always produce the identical URL. The file is deleted after one day — copy it to your own storage.

Errors

Status / Code Meaning
400 templateName missing.
500 (c: 1) The renderer failed — the message contains the render error details.