, "m": "", "payload": ...} — the m property tells you what went wrong. A few endpoints return plain-text errors; tolerate both. HTTP 401/403 indicate a missing token or insufficient permission level.For a step-by-step introduction with complete round-trip examples, read the Backend API article first.Submit print jobs and receive print-ready files, register external productions, create save tokens server-side and query production status.Produce print files and let Printess forward them to a fulfillment partner (HP Siteflow, email, Dropbox, FTP and more). Save the recipient address first, then start the dropship production.Query the print jobs (orders) you started: order history, output file URLs, and filter helpers for building order screens.Manage save tokens — the ids that identify your buyers’ saved designs — plus cart thumbnails and AI access keys.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.Generate product images (mockups) of your templates — with form field values applied, so you can render one image per variant.Send your Printess Service Token as a bearer token in the Authorization header of every request:You find the Service Token in the Account Portal: open the Account page and scroll to the User Tokens section at the bottom. Click the copy button next to the Service Token. Read Authorization Tokens for the difference between the Shop Token and the Service Token.The Service Token satisfies every permission level. Each endpoint shows the minimum level it accepts as a badge (user, owner, service, shop). This is relevant only if you create restricted tokens for parts of your infrastructure.The Service Token gives full access to your Printess account. Use it only on your server. Never put it into code that runs in a browser or into a public repository.Every endpoint has a Try It Live box. Edit the JSON request body and click Send Request to call the real API from your browser.Try It Live sends real requests to your account. A production or dropship call starts a real job, which can create costs and send real orders to your fulfillment partner. Use test save tokens and test product definitions.Download a ready-to-use collection with all endpoints and their minimal payloads. Postman collections (v2.1 format) also import into Insomnia, Bruno, Hoppscotch and most other API clients. After the import, set the serviceToken variable to your Service Token." /> , "m": "", "payload": ...} — the m property tells you what went wrong. A few endpoints return plain-text errors; tolerate both. HTTP 401/403 indicate a missing token or insufficient permission level.For a step-by-step introduction with complete round-trip examples, read the Backend API article first.Submit print jobs and receive print-ready files, register external productions, create save tokens server-side and query production status.Produce print files and let Printess forward them to a fulfillment partner (HP Siteflow, email, Dropbox, FTP and more). Save the recipient address first, then start the dropship production.Query the print jobs (orders) you started: order history, output file URLs, and filter helpers for building order screens.Manage save tokens — the ids that identify your buyers’ saved designs — plus cart thumbnails and AI access keys.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.Generate product images (mockups) of your templates — with form field values applied, so you can render one image per variant.Send your Printess Service Token as a bearer token in the Authorization header of every request:You find the Service Token in the Account Portal: open the Account page and scroll to the User Tokens section at the bottom. Click the copy button next to the Service Token. Read Authorization Tokens for the difference between the Shop Token and the Service Token.The Service Token satisfies every permission level. Each endpoint shows the minimum level it accepts as a badge (user, owner, service, shop). This is relevant only if you create restricted tokens for parts of your infrastructure.The Service Token gives full access to your Printess account. Use it only on your server. Never put it into code that runs in a browser or into a public repository.Every endpoint has a Try It Live box. Edit the JSON request body and click Send Request to call the real API from your browser.Try It Live sends real requests to your account. A production or dropship call starts a real job, which can create costs and send real orders to your fulfillment partner. Use test save tokens and test product definitions.Download a ready-to-use collection with all endpoints and their minimal payloads. Postman collections (v2.1 format) also import into Insomnia, Bruno, Hoppscotch and most other API clients. After the import, set the serviceToken variable to your Service Token." />

Backend API Reference

The Printess Public API lets your shop or backend produce print-ready files from personalized designs, manage save tokens, generate product mockups and hand finished orders to fulfillment partners.

All endpoints are HTTP POST with a JSON body (Content-Type: application/json) at the base URL https://api.printess.com. Paths are case-insensitive.

The typical shop workflow: the buyer personalizes a product in the Printess buyer-side editor on your product page. When the design is finished, the editor hands your shop a save token (st:...) plus a thumbnail for the cart. A save token is valid for 30 days. When the customer completes the purchase: 1. extend the save token lifetime (/savetoken/lifetime/extend) so the design survives for reprints, 2. start production — either /production/produce (you handle printing yourself) or /dropship/produce (Printess forwards the files to your fulfillment partner), 3. track progress via /production/status/get, the callbackUrl, or /orders/list / /dropship/orders/list.

Errors: failed requests return a JSON body {"c": <error code>, "m": "<message>", "payload": ...} — the m property tells you what went wrong. A few endpoints return plain-text errors; tolerate both. HTTP 401/403 indicate a missing token or insufficient permission level.

For a step-by-step introduction with complete round-trip examples, read the Backend API article first.

Production

Submit print jobs and receive print-ready files, register external productions, create save tokens server-side and query production status.

Endpoint Path Summary
Produce Print Files /production/produce The main production endpoint: renders a template or saved design into print-ready files.
Produce (Simple) /production/produce/simple Minimal production call: template + your order id, PDF at the given dpi.
Create Save Token /production/savetoken/create Create a saved design server-side — with form fields, merges, images and actions.
Create Save Token with Form Fields /production/savetoken/create/with/formfields Fast save token creation from a template plus form field values.
Produce Shop Proof /production/shop/proof Low-resolution proof rendering, callable with a shop token from the storefront.
Register External Production /production/external Register an order that is produced outside Printess and read the design’s form field values.
Register External Production (v2) /production/v2/external Register an external order and get the design’s evaluated form field values and image data.
Retry Order /order/retry Re-run an existing production order under a new job id.
Get Job Status /production/status/get Poll the full status and result of a production job.
Get Job Status (PDF) /production/status/pdf/get Simplified status: just the PDF URLs, or the error.
Download Order Files as Zip /production/orders/files/zip Bundle the output files of one or more orders into a single zip download.

Dropshipping

Produce print files and let Printess forward them to a fulfillment partner (HP Siteflow, email, Dropbox, FTP and more). Save the recipient address first, then start the dropship production.

Endpoint Path Summary
Save Dropship Address /dropshipData/save Stores the recipient address for a dropship order and returns its id.
Produce and Dropship /dropship/produce Renders the print files and forwards the finished order to your fulfillment partner.
List Dropship Orders /dropship/orders/list Query the fulfillment state and tracking information of your dropship orders.

Orders

Query the print jobs (orders) you started: order history, output file URLs, and filter helpers for building order screens.

Endpoint Path Summary
List Orders /orders/list Search your production orders and read their state and output file URLs.
Unique Order Template Names /orders/templates/unique Distinct template names across your orders — for filter dropdowns.
Unique Order Origins /orders/origins/unique Distinct origin tags across your orders — for filter dropdowns.
List Submission Errors /submission/errors/list Rejected produce requests — see what your integration sent and why it failed.

Save Tokens and Shop

Manage save tokens — the ids that identify your buyers’ saved designs — plus cart thumbnails and AI access keys.

Endpoint Path Summary
Extend Save Token Lifetime /savetoken/lifetime/extend Keep a purchased design (and its uploaded images) available beyond the default 30 days.
List Save Tokens /savetoken/list Browse and search all live save tokens of your account.
Save Token Info /shop/template/info Check whether a save token still exists and when it expires.
Basket Thumbnail URL /shop/basket/thumbnail Get an image URL showing the buyer’s design — for the cart and order emails.
Delete Save Token /saveToken/delete Permanently delete a saved design — e.g. for GDPR requests or cart cleanup.
Create AI Auth Key /ai/auth/create Mint a per-buyer AI usage key with its own budget.

Templates and Directories

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.

Endpoint Path Summary
List Template Form Fields /template/formFields/list Read the product options (form fields) of a template — the schema for your product page UI.
Load My Templates /templates/user/load List the templates of your account, filterable by folder, name and type.
Load Recent Templates /templates/user/recent/load Your most recently edited templates.
Load New Section Templates /templates/user/new/load Published templates curated as starting points for new designs.
Load Shared Templates /templates/user/shared/load Templates another account shared with you.
List All Visible Templates /templates/list Everything you can see, grouped by owning account.
Template Exists /template/exists Pre-flight check whether templates exist (and are published).
Template Details /template/details Thumbnails, document info and pricing categories of one template.
Create Template from Save Token /template/from/saveToken Turn a buyer’s saved design into a reusable template in your account.
Load Directory Tree /directories/load The complete template folder tree of your account.
Load NEW-SECTION Directory /directory/load Load the special NEW-SECTION folder subtree.

Mockups

Generate product images (mockups) of your templates — with form field values applied, so you can render one image per variant.

Endpoint Path Summary
Create Mockup URL /saas/mockup/url/create Instantly returns a mockup image URL — rendered and cached on first access.
Generate Mockup Image /saas/mockup/url/generate Renders a mockup now and returns the URL of the finished image file.

Authentication

Send your Printess Service Token as a bearer token in the Authorization header of every request:

Authorization: Bearer <YOUR_SERVICE_TOKEN>

You find the Service Token in the Account Portal: open the Account page and scroll to the User Tokens section at the bottom. Click the copy button next to the Service Token. Read Authorization Tokens for the difference between the Shop Token and the Service Token.

The Service Token satisfies every permission level. Each endpoint shows the minimum level it accepts as a badge (user, owner, service, shop). This is relevant only if you create restricted tokens for parts of your infrastructure.

The Service Token gives full access to your Printess account. Use it only on your server. Never put it into code that runs in a browser or into a public repository.

Try It Live

Every endpoint has a Try It Live box. Edit the JSON request body and click Send Request to call the real API from your browser.

  1. The first time you send a request, a dialog asks for your Service Token. Paste it and click Use Token.
  2. The Knowledge Base keeps the token only in this browser tab (sessionStorage). It is never written to a cookie and never sent anywhere except api.printess.com. Closing the tab deletes it.
  3. Click Forget Token in any Try It Live box to delete it earlier.

Try It Live sends real requests to your account. A production or dropship call starts a real job, which can create costs and send real orders to your fulfillment partner. Use test save tokens and test product definitions.

Import into Your API Testing Tool

Download a ready-to-use collection with all endpoints and their minimal payloads. Postman collections (v2.1 format) also import into Insomnia, Bruno, Hoppscotch and most other API clients. After the import, set the serviceToken variable to your Service Token.