How to Upload a Custom PSD Smart Object Template and Expose It as an API-Renderable Resource in Your POD Workflow

If you sell print-on-demand products through Etsy, Shopify, or your own platform, you have probably accumulated a folder full of premium PSD mockup files from Creative Market or Envato. Those files are expensive, carefully sourced, and often better than anything in a generic template library. The problem is that they sit on your hard drive and require Photoshop every time you want a new variation.

This guide bridges that gap. You will learn how to format a PSD correctly so Mockupanda can read it, how to upload it as a custom template, how to retrieve its ID via the REST API, and how to wire it into automated batch requests so your design drops into your own scenes without touching Photoshop again.

Why Custom PSD Templates Matter in an Automated Workflow

The problem with one-at-a-time Photoshop rendering

When you render mockups manually in Photoshop, every new design means opening a file, finding the Smart Object layer, pasting artwork, flattening, exporting, and saving. That sequence is fine for a handful of products. When you are launching a catalog of a hundred designs, or when a customer-facing app needs to generate listing images on the fly, manual rendering stops being practical.

An API-based approach flips the model. You send artwork to an endpoint, and rendered images come back in the same response. Mockupanda's REST API supports batch mode, sending up to twelve templates per request, and renders all of them in parallel. The bottleneck becomes how well your templates are set up, not how fast you can click through Photoshop.

What custom templates unlock that the built-in library cannot

The built-in template library covers a wide range of scenes, but it cannot cover every niche. If you sell art prints in a very specific interior style, or if your brand identity depends on a particular product photo you commissioned, you need your own scenes. Custom PSD templates let you bring exactly those assets into the same API workflow you use for built-in templates. Once uploaded, a custom template has its own ID and can be used with the same generate endpoint and batch syntax as a library template.

The key detail that makes this possible is that Mockupanda requires a Smart Object layer named Design to be the active layer when you save the PSD. That naming convention is how the renderer knows where to composite your artwork, and it is the same convention used by most commercial mockup packs, so files from Creative Market and Envato typically work without modification.

Takeaway: Before investing time in the upload process, confirm your PSD already has a Smart Object layer named Design. If it uses a different name, rename it in Photoshop before saving.

Preparing Your PSD for Upload

Smart Object layer requirements

The renderer looks for a layer named Design that is a Smart Object type. This layer acts as the placeholder that gets swapped out at render time. When the layer is replaced, the new artwork is automatically warped, scaled, and blended to match the surrounding scene, so perspective and lighting effects that sit on layers above the Smart Object stay intact.

Your PSD should be structured in roughly three parts. First, the Smart Object layer named Design itself. Second, the static background elements: the product surface, any physical props, the background texture. Third, effects layers placed above the Smart Object, such as lighting overlays, shadow layers, or color-grading adjustments. Effects placed above the Smart Object layer will appear on top of whatever artwork gets composited in, which is exactly the behavior you want for a realistic result.

The Design layer must also be the active (selected) layer when you save the file. This is a small step that is easy to miss: even if the layer is named correctly, if another layer is selected at save time, the file may not behave as expected on upload.

File size and format constraints

Mockupanda accepts custom PSD uploads up to 300 MB. That is large enough to accommodate high-resolution mockup packs with multiple layers and embedded assets. If your file is larger than that, flattening background elements or merging non-essential layers in Photoshop will usually bring it within range without affecting render quality.

For the artwork you will be sending through the API later, the limits are separate: a maximum file size of 20 MB per artwork upload, and a maximum output width of 4000 pixels (default is 2000 pixels). Render times for complex templates at the default size land in the two-to-four-second range, and at 4000 pixels in the three-to-five-second range, which is fast enough for real-time listing generation.

Takeaway: Save your PSD with the Design Smart Object layer selected, keep the file under 300 MB, and structure effects layers above the Smart Object so they composite correctly over incoming artwork.

Uploading the Template and Finding Its ID

Uploading via the dashboard

Once your PSD is ready, upload it through the Mockupanda dashboard. After the upload processes, the template appears in your account as a custom template. The dashboard displays each template's unique ID, and that ID is what you will use as template_id in every API call that references this scene.

Custom templates are attached to your account, not to the shared library, so they are only visible to API keys that belong to your account. The API response from GET /templates includes both the built-in library and your own templates, letting you work with both in the same codebase without any special switching logic.

Retrieving the template ID via the API

If you are building an automated pipeline and want to fetch your custom templates programmatically rather than copying IDs from the dashboard, use the GET /templates endpoint with the source parameter set to custom:

curl -X GET "https://www.mockupanda.com/api/v1/templates?source=custom" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response returns your uploaded templates with their IDs, names, and categories. Custom templates typically appear under the category My templates. You can also combine source=custom with the q parameter to run a semantic search across your own templates:

curl -X GET "https://www.mockupanda.com/api/v1/templates?source=custom&q=bedroom+lifestyle" \
  -H "Authorization: Bearer YOUR_API_KEY"

The q parameter uses hybrid search that matches meaning as well as words, so querying for a scene type rather than an exact file name still surfaces relevant results. If you have uploaded a large number of custom PSDs, this is a practical way to find the right template ID without paging through the full list.

You can also filter by type (print for wall art and poster templates, product for apparel, mugs, and other three-dimensional product templates) or by aspect ratio using the ratio parameter. For print templates, ratio accepts values like "2:3", "4:5", "square", "A4", or a decimal. That means if your upload is a portrait poster scene, you can confirm its ratio before wiring it into a workflow that expects a specific orientation.

Takeaway: Run GET /templates?source=custom after uploading to confirm the template registered correctly and to retrieve its ID for use in generate calls. Store that ID in your environment config or database so downstream services do not need to re-query it on every run.

Generating Mockups From Your Custom Template

Single-template generate call

With the template ID in hand, the generate call looks identical to a call using any built-in template. Send a POST to /api/v1/mockups/generate with your API key in the Authorization header and the template ID and artwork in the request body:

curl -X POST "https://www.mockupanda.com/api/v1/mockups/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "your-custom-template-id",
    "artwork_url": "https://your-cdn.com/designs/design-01.png"
  }'

If you prefer to upload the artwork file directly rather than providing a URL, use multipart/form-data and the artwork parameter instead of artwork_url. The file size limit is 20 MB per upload. For PNG artwork with a transparent background, transparency is preserved during compositing, which matters when your design does not fill the entire Smart Object area.

The response returns the rendered image. Mockupanda's stated render times are one to two seconds for simple templates and two to four seconds for complex ones.

Batch mode with custom and library templates mixed

One of the more useful aspects of treating your custom PSD as a standard template is that you can mix it freely with library templates in a single batch request. The template_ids array accepts up to twelve IDs per request, and those IDs can be any combination of built-in and custom:

curl -X POST "https://www.mockupanda.com/api/v1/mockups/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_ids": ["your-custom-template-id", "library-template-id-1", "library-template-id-2"],
    "artwork_url": "https://your-cdn.com/designs/design-01.png"
  }'

All templates in the batch render in parallel, so sending twelve IDs does not take twelve times as long. This is the core efficiency gain for POD sellers who want to generate a full set of listing images from a single API call rather than looping through sequential requests.

If you find yourself reusing the same combination of custom and library templates across many designs, grouping them into a Set is worth considering. Sets are named, ordered groups of templates saved in the app. Once created, you replace the whole template_ids array with a single set_id, and every template in the set renders from the same artwork in its saved order. Custom templates can be included in a set alongside built-in ones, so your PSD scene can be part of a reusable batch that you trigger with one parameter.

Takeaway: Test your custom template with a single template_id call first to verify the Smart Object replacement looks correct. Once confirmed, move it into your batch calls or a Set for production use.

Integrating Into Your POD Pipeline

Structuring API keys for multi-service workflows

If your POD operation runs across more than one service, for example a listing service, an order-fulfillment service, and a customer preview tool, it is worth creating separate API keys for each rather than sharing one. Mockupanda supports creating multiple API keys from Dashboard, API Keys, with no cap on the number of active keys per account.

Separate keys mean rate limits are independent. Each key gets 100 requests per minute and 10,000 requests per day. Keeping them separated also makes it easier to rotate or revoke a key for one service without affecting the others. If you are building a multi-tenant platform where different customers have distinct mockup sets, per-client keys give you clean isolation.

When a request exceeds the rate limit, the API returns a 429 Too Many Requests response with a retry_after field indicating how many seconds to wait. Building retry logic around that field is straightforward and prevents wasted credit spend on duplicate failed requests. Failed requests cost zero credits, so a retry after the specified delay is safe.

Filtering to find the right custom template for each design

In a catalog workflow where designs come in different proportions, you often need to match each design to templates that fit its aspect ratio rather than applying every template blindly. The GET /templates endpoint supports filtering by artwork_url or by artwork_width and artwork_height, returning only templates whose frame proportions match the artwork's shape. You can apply this to your custom templates by omitting source or by including source=custom.

This is especially useful when you have uploaded custom PSDs in multiple orientations, portrait, landscape, and square, and need to route each incoming design to the right subset. The artwork-matching filter keeps your generates clean and avoids the awkward result of a portrait design stretched into a landscape frame.

The ratio_tolerance parameter controls how strict the match is, expressed as a percentage. The default is 3 percent, which catches slight variations. Raising it toward the maximum of 25 percent is useful when you want to accept templates that will crop the artwork slightly at the edges, a common choice for art print sellers who prefer slight cropping over letterboxing.

Combining custom templates with Sets for catalog launches

When you are ready to launch a new design across your full catalog, the most efficient path is to have a Set that includes your custom PSD templates alongside your preferred library scenes. Create the Set once in the app, note the set_id, and your generate call becomes a two-parameter request: set_id and artwork_url. Every template in the set renders in parallel, and the response includes a standard batch payload with the set_id and set_name attached for easy logging.

For sellers scaling to hundreds of listings, this means the per-design work is essentially reduced to making one API call per design. The bulk mockup approach that Mockupanda is built around applies just as cleanly to your own PSD scenes as it does to library templates, because once uploaded, your custom template is a first-class resource in the same system.

Takeaway: Build your production workflow around Sets that include your custom templates. The set_id parameter collapses what would otherwise be a list of IDs into a single stable reference, making your API calls shorter and your pipeline easier to maintain when you add or retire templates.

Keeping Custom Templates Current

When to re-upload versus create a new template

If you need to update a custom PSD, for example because you sourced a better version of a scene or adjusted the lighting, the practical approach is to upload the revised file as a new template. This gives it a new ID, which means existing workflows that reference the old ID keep working until you explicitly switch them over. That separation between the old and new version is useful when you want to test the updated scene against a few designs before committing your whole catalog to it.

If the update is minor and you want to keep the same ID in all your existing calls, check whether your dashboard supports replacing the file for an existing custom template. Either way, verifying the result with a test generate call before updating your production set_id or template_id references is a step worth keeping in your deployment checklist.

Naming conventions that survive at scale

As your library of custom PSDs grows, a consistent naming convention saves time later. Template names appear in your dashboard and in API responses. Using descriptive names that include the product type, orientation, and style, such as poster-portrait-boho-bedroom or tshirt-front-flat-lay-dark, makes the q search parameter much more useful when you need to retrieve a specific template without paging through the full list.

If you are running a platform where multiple team members or microservices interact with the template library, documenting the custom template IDs and their names in a shared config file or database table prevents the situation where the same PSD gets uploaded multiple times under different names.

Takeaway: Treat your custom template IDs like any other infrastructure dependency: store them explicitly, give the uploaded PSDs descriptive names that make semantic search useful, and test any change to a template in isolation before rolling it into production Sets.

The gap between a folder of premium PSD mockup packs and a fully automated mockup API is smaller than it looks. The prerequisite is a correctly structured PSD with a Design Smart Object as the active layer, the file size within 300 MB, and a quick upload through the dashboard. After that, Mockupanda treats your custom scene exactly like any built-in template: retrievable by ID, filterable by ratio, composable into Sets, and renderable in parallel batches. That is the foundation of a POD workflow that scales with your catalog rather than against it.