Templates

A template is one authored artwork: its layers, which of them a customer may change, and the rules a customer’s changes must follow. It is the design, never the product. It names no item it prints on and carries no print size, so one template can serve a tee front, a tee back and a tote without being authored again.

Layers

A template is made of layers, each one painted element: text, an image or a shape. Layers are painted in order, lowest first, so a later layer covers an earlier one.

A layer is placed in proportions of the artwork, never in millimetres. The millimetres arrive only when a design is printed at a real size. A layer that reaches past the edge of the artwork is clipped there. A layer can be turned, scaled and flipped: mirrored left to right or top to bottom about its centre, which leaves it where it is.

A text’s size is a proportion too: a share of the artwork’s height, so the same design breaks its lines the same way on a label and on a banner. The builder shows the point size it prints at on the product you preview. A text layer’s text box says what happens when the text does not fit: keep the size and let the box grow, shrink the text down to a floor, then cut it or refuse it — or scale the text to fill the box. A box grows only as far as the limit you set allows from where it sits, its height limit a share of the artwork or a number of lines, and it can break a word too long for it onto the next line. A refused text is shown to the customer at its field. A box that cuts the text is your choice, so nothing warns about it; instead the builder tells you about how many characters of an offered text fit at the smallest size, in every font, weight and spacing the customer may choose, and offers to make that the text’s maximum length.

A text can also draw an outline around its letters and a shadow under them, each with its own colour. Their width, offset and blur are shares of the text’s drawn size, so an outline keeps its weight however large the text is set. Each part can be fixed or offered on its own: a customer may pick the outline’s colour while you fix its width.

A photo and a shape can draw an outline and a shadow too: a border round the photo, a stroke round the shape, drawn outside its edge, and a shadow cast by it. A photo can also round its corners, without becoming a shape; its outline and shadow follow them. Their sizes are shares of the shorter side of the layer’s box, so an effect keeps its weight as the layer is resized. A photo’s outline and shadow follow its box, or, if you choose, the picture’s own shape: a cut-out photo on a transparent background then casts a shadow shaped like the product. Each part can be fixed or offered on its own, as a text’s can; what they follow is always fixed. A photo can instead draw a sticker edge, white unless you choose a colour, round the picture’s own pixels as its crop shows them, with a width of its own; it shares the outline’s colour, a photo draws one or the other, never both, and a tiled picture draws none.

A photo can be adjusted: made lighter or darker, given more or less contrast or colour, and toned in black and white, sepia, a duotone that runs from one colour in its darkest tones to another in its lightest, or inverted. The adjustment is made to the photo’s own pixels, so the preview and the print file show the same picture. A duotone’s colours are process colours, never a spot ink. A photo can also be recoloured: every pixel you can see is drawn in one colour or ink, its transparency kept, so black lettering cut out of its background can print white on a dark product. A recolour prints as that ink, a spot on its own plate. The tone can be offered as a pick among the tones you tick, starting at yours, and each amount as a range; a duotone’s and a recolour’s colours stay yours. Pixel sets a photo’s adjustments too (set_photo_adjustments, in the studio and over MCP): on the template open in the builder as one step you can undo, and on any other as an edit of its draft, as every edit Pixel makes there.

Any layer can blend with the layers under it instead of covering them: multiply, screen, overlay, darken or lighten, so a pattern can be laid over a photo or a colour multiplied into it. The blend is worked out ink by ink in the print’s CMYK, and the preview works it out the same way, so the two agree. A layer in a spot ink cannot blend, and neither can one over a spot, as with a see-through layer. A blend is yours alone: customers are never offered it.

A text’s letter spacing, line height and case set how it is spaced and lettered. Letter spacing is a share of the drawn size added between the letters, so signs can spread capitals wide; line height is a share of the font’s own line spacing. The case draws the text as typed, in capitals, in small letters, or with each word’s first letter a capital, whatever the customer typed and with a dynamic value’s text included, while the text itself is kept as typed. A box that shrinks its text measures it with all three, so a name spaced wide shrinks sooner. Each can be fixed or offered like the text’s other settings.

A text’s fill, and a shape’s, can be a gradient instead of one colour: two to eight colours running at an angle, or out from a centre, across a shape’s box or across the text itself: a text’s gradient runs from its first letter to its last however wide its box is. It blends in CMYK, the way the press prints it, so the proof and the print file show the same blend; its colours are CMYK colours or colour inks, never a spot ink. A gradient is offered the way a colour is: the customer picks each of its colours from the fill’s palette, from any colour, or both, while its type, angle and positions stay yours.

A text can run along a curve instead of a straight line: an arc of the oval inside its box, a whole circle, or once round a shape’s outline from your library. The box is the curve’s size, so resizing the box resizes the curve. You choose the angle the text is centred at, clockwise from the top, and whether the letters stand on the curve or hang inside it, so a badge can read along its top and along its bottom. A curved text is one line, and a customer’s longer text shrinks along the curve exactly as it would in a straight box, then is cut or refused; it never runs past the curve’s end.

Dynamic values

A text can hold dynamic values beside its words, written out when the template is read or drawn rather than when you write it: a graduation sign reading Class of {date.year} says the current year every year, without being published again.

Value	Writes, on 21 October 2026
{date.year}	the current year, 2026
{date.nextYear}	next year, 2027
{date.month}	the month’s name, October
{date.academicYear}	the academic year, 2026/27; a new one starts on 1 August
{date.dayMonth}	the day and month, October 21
{date.monthYear}	the month and year, October 2026
{date.long}	the full date, October 21, 2026
{date.short}	the date in digits, 10/21/2026
{date.iso}	the date as ISO 8601 writes it, 2026-10-21
{date.custom(d.M.yyyy)}	the date in a pattern of your own, 21.10.2026: see Date patterns

A value is written in the language the template is read in: the one the read names with lang, such as GET /v1/templates/{id}?lang=de, which the SDK sends as the designer’s locale; without one, your workspace’s default language, set under Settings; else English. So {date.long} writes 21. Oktober 2026 in a German store and 21 oktober 2026 in a Swedish one, from one template. To fix a value’s language whoever reads it, name the language after a colon: {date.long:sv} always writes 21 oktober 2026, and {date.short:de} always writes 21.10.2026. Write {{ for a brace you mean literally. A text naming something that is no value is refused when you publish, naming it.

A fixed text may also name an editable text’s field key: Happy birthday {field.name} prints the customer’s name inside the greeting, so the two centre and wrap as one line. Until a customer has typed one, it shows the field’s default text, and {field.name ?? "friend"} prints friend when the customer leaves it empty. In the builder, the braces button beside a text’s content lists the template’s text fields by key, and renaming a key renames it in every text that names it.

Only the builder shows the names. The template a key reads, the designer and a customer’s text field all show what they write today. Today is the date in the timezone the read names with tz, such as GET /v1/templates/{id}?tz=Europe/Stockholm, and the SDK names the customer’s own. Without one it is your workspace’s timezone, set under Settings. A proof and a design keep the text they were made with, so a printed order never changes language or date afterwards; previews, thumbnails and mockups are drawn in your workspace’s timezone and default language.

Languages

A template is written in one language, its original, which is your workspace’s default. For each other language a customer may read it in, it can hold what differs, under localized: a layer’s text, its field’s label and help text, its place and size, its font and the fonts it offers, whether it shows at all; a group’s label.

{
  "localized": {
    "sv": {
      "layers": {
        "title": {
          "name": "Rubrik",
          "props": { "content": { "value": "Hej!", "label": "Din text" } }
        },
        "tagline": { "print": false }
      },
      "groups": { "text": { "label": "Din text" } }
    }
  }
}

A layer is named by its id, its fields by their names in the template, and a prop’s change is merged over the original’s, so what it does not name stays as the original has it. A language cannot add or remove a layer, or change whether a customer may change a field or its field key. "print": false hides a layer in that language: it keeps its place, prints nothing and offers the customer nothing there. A template is published, versioned and restored with its languages, and publishing refuses a language that names a layer, group or prop the template does not have, or that breaks one of the template’s rules, naming the language.

In the builder, choose a language in the top bar to edit the template as it reads there. What you change is kept for that language alone, and each property shows whether it is still the original’s; Reset to original takes the language back to it. Layers are added, removed and moved in the original. When you save a change to the original that some language has its own value for, the builder asks, change by change, whether those languages take it (Apply to all) or keep their own (Keep theirs).

A template is read in a language: the one the request names with lang, such as GET /v1/templates/{id}?lang=sv, which the SDK sends as the designer’s locale; without one, your workspace’s default. The answer is the original with that language’s changes merged in, the original’s wherever the language changes nothing, and says which language it was read in; it never carries localized. A validation, a proof and a design are made in the same language, which is also the one dynamic values are written in. A design records it as its language, and its print file is the design as it was made in that language. What a customer types is theirs, in every language.

A layer’s name is for you. Customers are not shown it, but it is part of the published template. The builder names a new layer by its kind, or by the shape or picture it holds, numbered when another layer has that name; you can rename it.

What a customer may change

Each setting of a layer — a text’s content, its font, its colour, an image, the layer’s position — can be marked Editable. A new layer starts with every setting fixed: you choose what customers may change. A layer is customer-editable when at least one of its settings is. A layer with nothing editable is pure decoration.

Where a customer picks, you choose what they pick from: a colour from a palette, a picture from your presets or their own upload — for an image, a shape painted with a picture, or the background — a shape from the ones you offer. Every editable setting also carries its limits, and a design that breaks one is refused. An image’s picture may be required: the customer must then choose or upload one, and a design without it is refused. A picture may also cut out a customer’s upload: their photo’s subject is kept on a transparent background, as a new upload in its place, paid from your credits. It never holds the customer up: one that cannot be cut out is used as it is.

A layer’s content may require change: a text’s words, an image’s picture, a shape’s outline or its fill. Mark it when the default is a placeholder, a “NAME” or a sample photo, that must never be printed as it is. The customer then has to change it, and a design still holding the template’s default is refused at validate, proof and commit, naming the layer and the setting with the rule unchanged. The preview still shows the placeholder until they do. Only a setting the customer may change can require it, and only a layer’s content: publishing a template that asks it of a fixed setting, a font, the background or die-cut, or a text whose placeholder holds a dynamic value such as {date.year} is refused.

The picture a layer starts on and the presets you offer are separate. The starting picture need not be a preset: a sample photo can stand in the preview until the customer chooses one of your presets or uploads their own, and it is never offered to them. Untick it among the presets to stop offering it; it stays the starting picture. In the builder, the presets are folded away under one row while a layer offers none.

A picture a customer may upload into can allow upscaling: a photo too small for the size the customer chose then gets an upscale button before the proof, which makes a sharper, larger copy paid from your credits. “Show the upscale button below” is where the button appears: a photo under that resolution at its placed size gets it. It is the template’s minimum print resolution unless you set one. “Upscale to” is the resolution the button lifts the photo to, and what the upscale is priced by: the first unless you set your own, lower or higher. So “below 50, to 100” offers the button for a photo under 50 dpi and lifts it to about 100, while the template’s minimum resolution stays its own setting. A photo already at “Upscale to” is offered nothing. When “Upscale to” is under the minimum resolution, an upscaled photo still falls short of it and the low-resolution warning still shows, and the builder says so: raise the target or lower the minimum.

Layers a customer adds

A template can let a customer add layers of their own: another line of text, another picture, another shape. On the artwork’s Offered tab, Added by customers sets, for each kind, how many a customer may add, where they show in the form, where a new one lands on the artwork, and what each one starts as. It starts one of two ways:

• From a layer: a copy of a layer of the template, with its look and what it offers. Later edits to that layer do not follow it. A guide layer makes a good source, since it never prints.
• Its own look: a definition made in the dialog, with defaults and offered fields of its own. It needs no layer of that kind on the template.

Either way the customer may change only what it offers. The designer, the print and Pixel treat both alike.

Field keys

An editable setting may carry a field key: your own word for it, such as name, class or photo. What a customer enters in a keyed setting belongs to the key rather than to the layer, so when your store lets the customer try another template, every setting with the same key shows what they entered, and so does every side of an item printed on several, such as a shirt’s front and back. A setting without a key keeps its value in its own template.

Set a key on the setting’s card under Offered. A key names one setting of a template: the builder refuses one another setting already has. Use the same words across the templates a customer may switch between; which templates those are is up to your store. A picture’s crop is not carried, since it was framed for the other template’s box.

Palettes

A palette is a named list of colours, each with the name a customer picks it by. Palettes are not part of a template: they are kept once in your palette library, on the studio’s Palettes page, and an editable colour offers one of them. A palette that twenty templates offer is one palette, so correcting a colour there corrects every draft that offers it. A published version keeps each palette as it was when it was published, under the name it had then.

Deleting a palette that templates use keeps their colours: each template’s draft gets the colours it used as its own, offered and painted as before, and no longer changes with your library. Published versions keep the palette they were published with until you republish.

A palette’s colour may be one of your inks: a colour, stored as the CMYK it prints as, or a spot ink. That ink is then used by every template offering the palette: publishing keeps it as it was, and deleting the ink gives the palette its colour instead.

Customers pick a colour by its name and send that name with their design, so renaming or removing a colour changes what they choose from. Orders already placed keep the old name.

A colour may also have a name in each language you sell in. A designer shown in that language reads it under the swatch and in the cart line it lists, while the design keeps the colour’s own name, so it reads the same in every language.

Groups and the customer’s form

Layers are bundled into named groups. The groups are the steps of the customer’s form, top group first, and the layers in a group are that step’s fields, in order. That order is separate from paint order: a backdrop can paint behind everything and still be the last thing a customer is asked about. Order by canvas in the builder sets the form’s order from paint order once, lowest layer first; it moves nothing on the canvas, and the two orders stay separate afterwards.

A layer needs a group only when it offers the customer something: a layer in no group is in no step, so its editable settings reach no customer, and publishing warns about each such layer. A decoration can stay in no group. A new layer joins a group only when you add it from one, and you can move a layer into a group or back to no group at any time. Deleting a group moves its layers into a neighbouring one; deleting the only group leaves them in no group.

The reverse holds too: a group whose layers offer the customer nothing has nothing to fill in or place, so the designer leaves that step out of the form. Publishing warns about each such group, an empty one included, and the builder points at its step. Offer something on one of its layers, or delete the group.

Aspect ratio, tolerance and fit

A template has no print size. It has an aspect ratio you declare, such as 5:7, which is the proportion the artwork keeps wherever it prints.

Its ratio tolerance says how far a print size may stray from that ratio. 0 means only that exact ratio prints; a larger tolerance lets you sell the design at sizes in a slightly different proportion. A size outside the tolerance is refused.

Its fit says what the artwork does at a size the tolerance admits but whose shape differs from the ratio. Cover fills the print edge to edge and crops the overflow; contain shows the whole artwork and leaves bands. A new template starts on cover. Under cover you may name the point the crop keeps in view, such as the top, so a face near the top edge is never cut off. You set both in the builder’s Plate section, and its tolerance preview shows each end of the band as it will print.

At such a size the customer’s canvas takes the size’s shape, so they see the crop or bands they get. Turn on Keep this shape at every size, under the fit, and the customer always designs at the template’s own ratio instead: the canvas grows and shrinks with the size but keeps its shape, and the print at the chosen size is cropped or banded by the fit, which the proof shows. A shop can override it for its own designer with the SDK’s drawAtTemplateRatio.

A template never repeats on its own: a design may lay it as a tile, again and again across the print, as on a sleeve, an all-over print or wrapping paper. How it is laid, and how large the tile is, is the design’s; see Designs.

The print size itself is chosen with each design: the customer picks one in the designer, or your server names it when it commits the design, and it is kept with the design from then on. When a design names a placement on a blank but no size, the artwork prints at the largest size of its own ratio that fits the placement’s usual print size.

Background and cut shape

The Background sits behind every layer, covering the whole artwork: a colour, an image, or nothing. With no background, whatever nothing is painted on shows the product’s own material. An image background, like an image layer and a shape painted with a picture, covers its area, fits inside it, is stretched to it, or repeats as a tile at a tile size you choose, and either one may be offered to customers the way an image is — including, when it covers, letting them pan and zoom their picture inside it. You may also let customers choose how a picture fits, from the fits you offer, each with its own settings: pan and zoom when it covers, the tile size when it repeats.

The Cut shape is the outline the finished product is cut to — round for a coaster, a star for a sticker. It is one of your shapes drawn as one closed outline — any such shape can be a cut — or the plain rectangle until you pick one. It travels to the printshop as the line the finisher cuts. You may let customers choose the shape from a set you offer. Artwork that reaches the edge — a layer placed against it, or a background picture that fits inside — runs on past it into the print’s bleed, so a cut a little off the line still lands on the artwork carrying on, never folded back.

Drafts, versions and publishing

You edit a template in its draft, a working copy. Publishing turns the draft into the next version, which never changes again. Versions are addressed as <template id>@<version>, for example classic-tshirt@2. Customer designs are built against one version, so they stay exactly as the customer saw them.

A template’s status is one of:

• Draft — never published.
• Live — published, and served to storefronts.
• Paused — published, but switched off. Pausing takes the product off every storefront at once, and switching Live back on restores it. It creates no new version.

A connected store reads a template’s status from any of its versions, and its endpoint hears each pause and resume as one template.live_changed event.

A live template can have unpublished changes in its draft at the same time. Customers see the published version until you publish again.

Every save keeps the state it saved. The builder’s History lists them, newest first, with who saved each and which were published, and restoring one makes it the draft again as a new save, so nothing before it is lost. To roll a product back, restore the state an earlier version was published from and publish it. A template keeps its draft and the 100 unpublished saves before it; saves that were published are always kept.

Two people can have one draft open at once. When someone else saved or published the template since you opened it, your next save is refused: the builder says the template changed on the server, keeps your changes on screen, and pauses autosave. Save anyway then asks you to confirm, and writes your version over the newer one. What it replaced is still in History, so you can restore it. Autosave resumes after the save.

Showcase values

Your product images can show a filled-in example while the designer keeps the template’s own defaults. A showcase is a named set of values for the layers a customer may change: a real name, a real photo. A sign template whose designer opens on “NAME” can have its product photo read “Congratulations, Sam!”. A template can hold several, one per product photo, say.

Make one in the builder: Create showcase, beside Preview, puts the builder in showcase mode. Set the values of the layers customers may change on the canvas and in the inspector, any value you could set there, a picture from your library included, then Save as showcase and name it. Anything customers cannot change is refused while the mode is on. Choose a showcase in the mode’s bar to change it, rename it or delete it, Copy link for the address of its picture, and Check to see it as a customer would. A showcase holds only what differs from the template; every other layer shows its default. Done returns to the template as it was. Pixel saves, changes and deletes showcases too: at once on the template open in the builder, and on any other template after you approve its card, which lists each template it changes and offers Undo once applied.

On the Templates page, the template’s details pane lists the showcases of the document its preview shows, the draft’s or the shown version’s. Pick one to see the preview drawn with it, and Show defaults to go back.

Showcases are published with the template. Publishing checks each one as it would check a customer’s design, and refuses a showcase whose values the template no longer accepts or that names a picture outside your workspace. Changing one takes effect for shops when you publish again.

Only images use them. GET /t/{id}/preview.png?showcase=<id> and GET /t/{id}/mockup.png?showcase=<id> draw a showcase; without showcase they draw the defaults, and an id the version does not hold answers 404 showcase_not_found. A template read lists its showcases as showcases: [{ id, name, previewUrl }]: previewUrl is a link to that showcase’s preview which, like the template’s own previewUrl, opens with no key for an hour or two, so a catalogue can show it in a plain image element. The showcase is signed into the link, and a link naming one the version does not hold answers 404 showcase_not_found. The designer, designs, proofs and prints always start from the template’s own values.

Deleting a template

Deleting a template removes it from your templates, from every list and picker, and from the API: no new design, proof or share link starts from it, and its designer links stop working. The designs and orders already made from it keep working: each still opens, can be corrected and printed, and still shows the template’s name. A deleted template’s id stays taken, so no new template can use it. Deleting needs the templates:delete permission.

Related

• Blanks — the items a template prints on.
• Designs — what a customer makes from a template.
• Embed the designer — how customers fill a template in.