# Catalog & placements

> Catalog products, variants and options, placements (print areas), recommended artwork sizes, DPI and file requirements.

Source: https://swaglists.com/docs/catalog

The catalog is everything we can make for you: t-shirts, hoodies, posters, mugs and more. Each **catalog product** has **variants** (combinations of options like color and size) and **placements** — the areas you can print on. Prices in the catalog are **your wholesale prices**.

```text
catalog_product  "Classic Unisex Tee"  (cp_…)
├── options     Color: Black, White, …   Size: S, M, L, …
├── variants    cv_… "Black / M"  price 1299  available ✓
│               cv_… "White / L"  price 1299  available ✓
├── placements  front   15 × 18 in → 4500 × 5400 px at 300 DPI
│               back    15 × 18 in → 4500 × 5400 px
└── mockup_templates   photo + print-area rectangle per placement/color
```

## Browse the catalog

```bash title="cURL"
# Featured first; filter by search term, category, technique
curl "https://swaglists.com/api/v1/catalog/products?q=tee&category=t-shirts&limit=10" \
  -H "Authorization: Bearer $API_KEY"

# One product with every variant, placement and mockup template (id or slug)
curl https://swaglists.com/api/v1/catalog/products/classic-unisex-tee \
  -H "Authorization: Bearer $API_KEY"
```
```js title="Node.js"
const headers = { Authorization: `Bearer ${process.env.API_KEY}` };
const list = await (await fetch("https://swaglists.com/api/v1/catalog/products?q=tee&limit=10", { headers })).json();
const product = await (await fetch(`https://swaglists.com/api/v1/catalog/products/${list.data[0].id}`, { headers })).json();
for (const v of product.variants) console.log(v.id, v.title, v.price, v.available);
```
```python title="Python"
headers = {"Authorization": f"Bearer {os.environ['API_KEY']}"}
items = requests.get("https://swaglists.com/api/v1/catalog/products", params={"q": "tee", "limit": 10}, headers=headers).json()
product = requests.get(f"https://swaglists.com/api/v1/catalog/products/{items['data'][0]['id']}", headers=headers).json()
for v in product["variants"]:
    print(v["id"], v["title"], v["price"], v["available"])
```

| Filter | Example | Notes |
| --- | --- | --- |
| `q` | `tee` | Searches title, subtitle, brand and tags. |
| `category` | `t-shirts` or `cat_…` | Includes sub-categories. List them with `GET /catalog/categories`. |
| `technique` | `dtg`, `embroidery` | Print technique. |
| `featured` | `true` | Only featured products. |

The list is paginated like every list — see [Pagination](https://swaglists.com/docs/pagination.md). Only products you can sell are listed; a variant that is temporarily unavailable shows `"available": false`.

## Variants and options

A catalog product's `options` list the option names and values in display order (e.g. `Color` with hex swatches, `Size`). Each **catalog variant** has:

- `id` (`cv_…`) — what you reference when you create products or order with inline designs,
- `options` — e.g. `{"Color": "Black", "Size": "M"}`, plus `color`, `color_hex`, `size` shortcuts,
- `price` — your wholesale unit price in cents with artwork on the **first placement**,
- `available` — whether it can be ordered right now.

`price_from` on the product is the lowest variant price. Prices can change over time; you get a [`catalog.price_changed`](https://swaglists.com/docs/events.md#catalog.price_changed) event when a variant your products use changes price.

## Placements

A **placement** is a printable area. Its `key` (`front`, `back`, `left_sleeve`, `embroidery_chest_left`, …) is what you use in designs. Each placement tells you exactly what artwork it needs:

| Field | Meaning |
| --- | --- |
| `key`, `label` | Identifier for designs, display name. |
| `technique` | How it is printed (`dtg`, `embroidery`, `sublimation`, `digital`, …). |
| `width_in`, `height_in`, `aspect_ratio` | Physical size of the print area and width ÷ height. |
| `recommended_width_px`, `recommended_height_px` | Artwork size that covers the whole area at **300 DPI**. |
| `min_dpi` | Below this effective resolution you get a `dpi_low` warning. |
| `required` | The product needs artwork on this placement. |
| `file_requirements` | Accepted formats, max size, color profile, transparency. |

Extra placements can cost extra: the variant `price` includes the first placement; a product with artwork on several placements has a higher `price` on its variants. [Estimate](https://swaglists.com/docs/pricing.md) an order to see the exact total.

## Artwork requirements

- **Formats:** PNG (recommended, with transparency), JPEG, WebP, TIFF, GIF (first frame) and SVG (sanitized and rasterized).
- **Size:** up to 100 MB and 30,000 px per side.
- **Color:** sRGB. Transparent pixels are not printed.
- **Resolution:** aim for 300 DPI at the printed size — the placement's `recommended_width_px` × `recommended_height_px` when the artwork fills the area.

### DPI explained

Effective DPI is the artwork's pixels divided by the inches it is printed at:

```text
effective DPI = artwork width (px) ÷ (placement width (in) × layer width fraction)
```

For example, a 3000 px wide image printed across the full 15 in front of a tee is 3000 ÷ 15 = **200 DPI**. Printed 10 in wide (width fraction 0.667) it is 3000 ÷ 10 = **300 DPI**.

| Effective DPI | Result |
| --- | --- |
| 300 or more | Ideal. |
| 150–299 | Fine for most products. |
| Below 150 (or the placement's `min_dpi`) | Accepted with a `dpi_low` warning — may look slightly soft. |
| Below 75 | Rejected with `artwork_resolution_too_low`. |

## Mockup templates

`mockup_templates` let you render previews in your own UI: each has a photo (`image_url`), the placement it shows, an optional `color` it belongs to, and `print_area` — where the print area sits on the photo, as fractions of the photo size. Draw the artwork into that rectangle using the same [transform](https://swaglists.com/docs/designs.md) as your design. When you create a product, we render its mockups for you (`product.mockups`).

Catalog image URLs (`images[].url`, variant `image_url`, mockup template `image_url`) don't expire, so you can display them directly in your store.

## Production time

`production_days` (`min`/`max` business days) is how long we need before handing the order to the carrier. Shipping rates add transit time; `estimated_delivery_days` on [shipping rates](https://swaglists.com/docs/shipping.md) includes both.