Smart objects

A smart object is a Photoshop layer that holds image data as a container rather than as flat pixels. In a mockup template it marks where artwork goes. Uploading a PSD returns one entry per visible smart object, and that entry is how you address the area at render time. When a smart object holds smart objects or live text of its own, its entry lists those too.

Upload lists visible smart objects only, at every depth. Turn on every layer you plan to fill before you send the file.

What an entry describes

An entry carries the layer as the designer built it, plus the handle you send back. Upload a PSD walks through the call, and Create a mockup from a PSD shows the whole response body next to the request that produced it.

Field	What it tells you
`uuid`	The handle you send back in a render.
`name`, `layer_name`	The layer as the designer named it. `layer_name` is the raw PSD name.
`size`	The area’s own width and height. Author artwork at these numbers.
`position`	Where the area lands after transforms, as `x`, `y`, `width` and `height` in pixels. A top-level entry is measured on the canvas, a nested entry inside its parent smart object’s document. Use it for previews.
`quad`	The four corner points when the area carries a perspective transform, in the same frame as `position`. Included on Scale plans.
`blend_mode`	The blend mode the layer was authored with.
`smart_objects`	The smart objects inside this one, as entries of this same shape, in their document’s layer order. Present only when there are some.
`text_layers`	The live text inside this one, shaped like a top-level text layer entry. Present only when there is some.
`required`	Whether the template expects this area to be filled.

Address an area in a render

A render takes the template’s mockup_uuid and a smart_objects array. Send one entry per area you want to change, keyed on the uuid that upload gave you, and leave the rest out. Anything you omit renders as the designer authored it. A template can hold as many areas as the designer built, and a single render can fill several of them at once. Every entry needs an asset, a color, or both, and an entry that carries neither comes back as 422. The same entry can also carry a colour overlay and adjustment values alongside the artwork, so one area can change image, tint and tone in one pass. Artwork placement takes fit, size, position, rotation, colour and tone field by field, Fit and blend modes covers how artwork meets an area, and Render a PSD mockup holds the request and response shapes.

Fill a smart object inside another

A sheet of tiles, a label or a pattern is often built as its own document and placed as one smart object. Its entry then lists the layers inside under smart_objects and text_layers, and each nested smart object can list its own in turn. The top-level arrays still hold only the outermost layers. A nested slot is filled like a top-level one: put its uuid in the request’s smart_objects or text_layers array, beside any other entries. The request still costs one render, however deep the slots it fills.

{
  "uuid": "4c1e9a07-2b6d-4f83-9e15-7a0d3c8b2e61",
  "name": "Design",
  "size": { "width": 4000, "height": 4000 },
  "position": {
    "x": 520, "y": 640, "width": 2960, "height": 2960
  },
  "smart_objects": [
    {
      "uuid": "e83f2a51-6c0d-4b97-8a24-1f5e9d7c3b08",
      "name": "1",
      "size": { "width": 800, "height": 800 },
      "position": {
        "x": 0, "y": 0, "width": 800, "height": 800
      }
    }
  ],
  "text_layers": [
    {
      "uuid": "7a2d9c40-1e85-4b36-9f07-3c6e8b1d5a92",
      "name": "Caption",
      "text_content": "YOUR TEXT"
    }
  ]
}

{
  "mockup_uuid": "MOCKUP_UUID",
  "smart_objects": [
    {
      "uuid": "e83f2a51-6c0d-4b97-8a24-1f5e9d7c3b08",
      "asset": {
        "url": "https://example.com/tile.png",
        "fit": "crop"
      }
    }
  ],
  "text_layers": [
    {
      "uuid": "7a2d9c40-1e85-4b36-9f07-3c6e8b1d5a92",
      "text": "Spring drop"
    }
  ]
}

A smart object takes artwork either as a whole or through its contents. A request that gives a parent smart object an asset and also fills or hides a layer inside it returns 422 with NESTED_SLOT_CONFLICT. A color on the parent is fine beside entries for the layers inside it. A template uploaded before 5 October 2026 shows its nested slots once the file is uploaded again. That upload is a new template with its own uuids.

Match slots by name, not by order

Array order follows the Photoshop layer stack, so a designer who reorders layers changes it, and code that reaches for the first entry quietly starts filling the wrong area. Build a lookup from the names your template is authored with: read name on each entry, keep the uuid it belongs to, and resolve the slot by name when you render. If a name your code expects is not in the template, fail loudly instead of falling back to a position, because that fallback ships a wrong print file rather than an error. Names repeat across parents. A tile named 1 can sit inside two different smart objects, so build the lookup per parent: first the parent smart object, then the name inside it.

Linked and hidden smart objects

A smart object whose content lives in an external file, such as @artwork.psb, uploads and renders from its placement geometry, so you do not need to run Embed Linked first. Embedding still gives the highest fidelity. When a linked smart object carries no usable placement geometry, the render returns a permanent 422 with LINKED_SMART_OBJECT_CONTENT_MISSING. That one does not clear on retry. Run Layer > Smart Objects > Embed Linked in Photoshop and upload the file again, or send the artwork in the render body. Errors lists every code and says which are worth retrying. A smart object that is hidden in Photoshop is not exposed as a slot and is not rendered, whether it sits at the top level or inside another smart object. Uploads that contain one come back flagged, so you know which layers to turn on before uploading again. Hidden text layers behave differently, and both rules are on Hidden layers.

Overview

PSD mockups

Photo mockups

Text and fonts

Integrations

Reference

Advanced

Choosing an approach

Troubleshooting

Working with the API

Account and billing

Changes

What an entry describes

Address an area in a render

Fill a smart object inside another

Match slots by name, not by order

Linked and hidden smart objects

Learn more

Artwork placement

Fit and blend modes

Next steps

Upload a PSD

Render a PSD mockup

​What an entry describes

​Address an area in a render

​Fill a smart object inside another

​Match slots by name, not by order

​Linked and hidden smart objects

​Learn more

Artwork placement

Fit and blend modes

​Next steps

Upload a PSD

Render a PSD mockup

What an entry describes

Address an area in a render

Fill a smart object inside another

Match slots by name, not by order

Linked and hidden smart objects

Learn more

Next steps