Designs & transforms

How artwork is placed on a print area — layers, the position (transform) model with a worked example, defaults and resolution checks.

A design puts one or more artwork layers on a placement. Designs are part of products (and of order items with inline designs):

{
  "designs": [
    {
      "placement": "front",
      "layers": [
        { "file_id": "file_01k8x3y1q3w5e7r9t1y3u5i7o9", "position": { "x": 0.1667, "y": 0.05, "width": 0.6667, "height": 0.5556, "rotation": 0 } },
        { "url": "https://cdn.example.com/badge.png", "opacity": 0.9 }
      ]
    }
  ]
}

• One entry per placement (placement = the placement key), up to 20 layers each, drawn bottom to top.
• Each layer references an uploaded file (file_id) or a public image url that we download for you.
• position (alias transform) places the layer; omit it to center the artwork and fit it inside the area.
• opacity is 0–1 (default 1).

We generate the print-ready file for production ourselves, at the exact size the product needs, from your artwork and these positions — so you only ever think in fractions of the print area.

#The position model

Positions are fractions of the print area, measured from its top-left corner:

 (0,0) ─────────────────── x ───────────────────► (1,0)
   │  print area (the placement)
   │
   │        x = 0.1667
   │        ├─────┐
   │        ┌──────────────────────┐  ┬ y = 0.05
   │        │                      │  │
   y        │       artwork        │  │ height = 0.5556
   │        │                      │  │
   │        └──────────────────────┘  ┴
   │        ├──── width = 0.6667 ───┤
   ▼
 (0,1)                                           (1,1)

• x/y describe the un-rotated box; rotation turns it around its center.
• Values outside 0–1 are allowed (up to ±10) for intentional bleed: whatever falls outside the area is cropped. A layer entirely outside gets a layer_outside_area warning; if no layer is visible the design is rejected (design_not_visible).
• The artwork is scaled to fill the box exactly. To avoid stretching, keep the box's aspect ratio equal to the artwork's (see below).

#Keeping the aspect ratio

Because width and height are fractions of different lengths, the box's real aspect ratio is:

box aspect = (width × area_width) ÷ (height × area_height) = (width ÷ height) × placement.aspect_ratio

So for artwork of art_w × art_h pixels, choose a width and compute:

height = width × placement.aspect_ratio × art_h ÷ art_w

#Worked example

A tee's front placement is 15 × 18 in (aspect_ratio 0.8333, recommended 4500 × 5400 px). Your logo is a 3000 × 3000 px PNG. You want it 10 in wide, centered horizontally, 0.9 in below the top of the print area.

1. width = 10 in ÷ 15 in = 0.6667
2. height = 0.6667 × 0.8333 × 3000 ÷ 3000 = 0.5556 (= 10 in ÷ 18 in, so the logo stays square)
3. x = (1 − 0.6667) ÷ 2 = 0.1667 (centered)
4. y = 0.9 in ÷ 18 in = 0.05
5. Effective DPI = 3000 px ÷ 10 in = 300 DPI ✓

{ "x": 0.1667, "y": 0.05, "width": 0.6667, "height": 0.5556, "rotation": 0 }

Without a position, the same logo would get the default contain & center position — as large as possible inside the area, centered:

{ "x": 0, "y": 0.083333, "width": 1, "height": 0.833333, "rotation": 0 }

That prints it 15 in wide (3000 px ÷ 15 in = 200 DPI — fine, above the 150 DPI warning threshold).

// Position for artwork `artW × artH` px, `widthIn` inches wide, centered, `topIn` inches from the top.
function position(placement, artW, artH, widthIn, topIn = 0) {
  const width = widthIn / placement.width_in;
  const height = width * placement.aspect_ratio * (artH / artW);
  return { x: (1 - width) / 2, y: topIn / placement.height_in, width, height, rotation: 0 };
}
// position({ width_in: 15, height_in: 18, aspect_ratio: 15 / 18 }, 3000, 3000, 10, 0.9)
// → { x: 0.1667, y: 0.05, width: 0.6667, height: 0.5556, rotation: 0 }

def position(placement, art_w, art_h, width_in, top_in=0.0):
    width = width_in / placement["width_in"]
    height = width * placement["aspect_ratio"] * art_h / art_w
    return {"x": (1 - width) / 2, "y": top_in / placement["height_in"], "width": width, "height": height, "rotation": 0}

#Resolution checks

When you create or update a product we compute each layer's effective DPI from the placement size and the layer's size:

• below 150 DPI (or the placement's min_dpi, if higher): the product is created with a dpi_low warning — it may print slightly soft;
• below 75 DPI: the request fails with artwork_resolution_too_low. Use a larger image or place it smaller.

Warnings are returned in the product response's warnings array (code, message, param, placement, effective_dpi).

#Tips for great prints

• Export artwork at the placement's recommended_width_px × recommended_height_px (300 DPI) and position it with fractions — never upscale small images.
• Use PNG with a transparent background; anything transparent is not printed (the garment color shows).
• Keep important content away from the very edges of the area.
• Embroidery placements need simple shapes and few colors; check the placement technique.
• Changing designs later (PATCH /products/{id} with designs) re-renders mockups; existing orders keep the designs they were created with.