Catalog & placements

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

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.

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

# 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"

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);

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"])

The list is paginated like every list — see Pagination. 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 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:

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 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:

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.

#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 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 includes both.