printful-m2480-crewneck-production

name: Printful M2480 Crewneck Production description: >- Complete pipeline for Cotton Heritage M2480 (catalog 411) PREMIUM crewneck sweatshirts on Printful. Covers product creation, variant management, branding placement, mockup generation, and Supabase integration. Use when creating M2480 crewneck products, generating mockups, updating branding, or managing PREMIUM tier crewneck sweatshirts.

Printful M2480 Production Pipeline — PREMIUM Tier

Full production pipeline for SKAPARA PREMIUM crewneck sweatshirts on the Cotton Heritage M2480 blank via Printful API. This is the PREMIUM tier crewneck counterpart to the MC1087 PREMIUM tee and M2580 PREMIUM hoodie.

For MC1087 PREMIUM tees, see the printful-mc1087 skill. For CC1717 SIGNATURE tees, see the printful-cc1717 skill. For Printify-based products (legacy DTG on P26), see the design-dtg skill.

Product Specifications

Key differentiator vs MC1087 tee: M2480 has 8 placements including label_inside (same as M2580 hoodie). Sleeves are 450x1800px VERTICAL (NOT 600x525 like MC1087 tees). Front/back share the same 1800x2400 canvas as MC1087.

Key differentiator vs M2580 hoodie: M2480 is a crewneck (no hood, no kangaroo pocket). Same Cotton Heritage PREMIUM brand family. Shares the vertical sleeve canvas format (450x1800).

Placements & Dimensions

All canvases at 150 DPI unless noted:

IMPORTANT — SLEEVE DIFFERENCE:

• MC1087 tees: 600x525 (horizontal)
• M2480 crewnecks: 450x1800 (vertical) — requires NEW branding asset!
• The sleeve_left branding file_id from MC1087 (950410444) is 600x525 and CANNOT be reused for M2480

CONSTRAINT: back and label_outside are mutually exclusive in Printful. v3 does NOT use back (saves $5.25/unit), so label_outside is technically available but currently unused.

Base Costs

Some non-EU colors have slightly higher base cost ($22.25 for S-XL). Use the EU colors which are $22.09.

Additional placement costs stack on top of base cost. A product with front + back + sleeve_left costs:

• S-XL: $22.09 + $5.25 + $2.20 = $29.54
• 2XL: TBD + $5.25 + $2.20 = TBD
• 3XL: TBD + $5.25 + $2.20 = TBD

Printful API Authentication

ALL requests require these headers:

Authorization: Bearer ${PRINTFUL_API_TOKEN}
X-PF-Store-Id: ${PRINTFUL_STORE_ID}
Content-Type: application/json

Env vars are in frontend/.env.local:

• PRINTFUL_API_TOKEN
• PRINTFUL_STORE_ID

Rate Limits

On HTTP 429: read x-ratelimit-reset header, wait that many seconds, retry.

Shared utility: For scripts, use import { createPrintfulClient } from './lib/printful-rate-limiter.mjs' — handles token bucket, 429 retry with jitter, proactive slowdown, and exponential backoff automatically.

File Upload Pattern

Printful requires files to be in its File Library before they can be used on products. Two upload methods:

Method 1: URL Upload (preferred for Supabase-hosted files)

curl -X POST https://api.printful.com/files \
  -H "Authorization: Bearer ${PRINTFUL_API_TOKEN}" \
  -H "X-PF-Store-Id: ${PRINTFUL_STORE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-supabase.supabase.co/storage/v1/object/public/designs/my-design.png",
    "filename": "my-design-front-1800x2400.png"
  }'

Method 2: Multipart Upload (for local files)

curl -X POST https://api.printful.com/files \
  -H "Authorization: Bearer ${PRINTFUL_API_TOKEN}" \
  -H "X-PF-Store-Id: ${PRINTFUL_STORE_ID}" \
  -F "file=@output/my-design-front-1800x2400.png" \
  -F "type=default"

Response returns id (integer file_id) and url (CDN preview URL). Save both:

• id is used in variant file placement updates
• url is used as image_url in mockup generation

Workflow 1: Create New M2480 Product

Step 1: Prepare Design Files

Design the main front canvas at 1800x2400px. Render branding assets per BRANDING.md.

Required files (v3 branding — no back):

1. Front design — 1800x2400 PNG (main design)
2. Sleeve left — 450x1800 PNG (SKAPARA wordmark vertical at 20% scale, file_id: 950653078)

CRITICAL: The sleeve_left branding asset for M2480 must be rendered at 450x1800 (vertical) with -resize 360x (20% width-based). See BRANDING.md for render commands. The MC1087 sleeve file (600x525) is INCOMPATIBLE.

v3 decision: No back branding (saves $5.25/unit). label_inside (S mark, file_id: 950649786) can only be added via Printful dashboard — API rejects it.

Step 2: Upload Design to Printful File Library

Upload the front design PNG via URL or multipart (see File Upload Pattern above). Save the returned file_id.

The sleeve_left branding file is already uploaded (20% scale wordmark):

• sleeve_left: 950653078 (450x1800, SKAPARA wordmark vertical, verified 2026-03-03)

Step 3: Create Sync Product

curl -X POST "https://api.printful.com/store/products" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-PF-Store-Id: ${STORE}" \
  -H "Content-Type: application/json" \
  -d '{
    "sync_product": {
      "name": "Product Name — SKAPARA",
      "thumbnail": "https://cdn.printful.com/.../design_preview.png"
    },
    "sync_variants": [
      {
        "variant_id": 11254,
        "retail_price": "49.95",
        "files": [
          {"type": "default", "id": FRONT_DESIGN_FILE_ID},
          {"type": "sleeve_left", "id": 950653078}
        ]
      },
      {
        "variant_id": 11255,
        "retail_price": "49.95",
        "files": [
          {"type": "default", "id": FRONT_DESIGN_FILE_ID},
          {"type": "sleeve_left", "id": 950653078}
        ]
      }
    ]
  }'

IMPORTANT: Include ALL active variants for the colors selected via design-first analysis. Select 2-5 colors from the 6 DARK EU palette based on design contrast (see MOCKUPS.md — Design Palette Analysis). Each color x 6 sizes. See VARIANTS.md for complete variant ID table.

CRITICAL — Adding variants to existing products (POST /store/products/{id}/variants):

• Files MUST use url field (NOT id alone) — using only id causes "There can only be one file for each placement" error
• Correct: { "type": "default", "url": "https://...design.png" }
• Wrong: { "type": "default", "id": 950267047 } (fails with 400)
• The initial product creation (POST /store/products) can use id, but individual variant creation requires url

Pricing: Set retail_price on each variant. The margin fixer cron will overwrite if margin is below 35%, so set the correct retail price from the start. Recommended retail for PREMIUM crewneck: $49.95-$54.95.

Step 4: Generate Mockups

Follow MOCKUPS.md workflow. Generate Ghost mockups for all active dark colors with Front and Left views (v3 — no Back).

Step 5: Update Supabase

const ts = Math.floor(Date.now() / 1000)

// 1. Create or update product in Supabase
// CRITICAL: Set BOTH category (slug string) AND category_id (FK UUID)
// The breadcrumb uses `category` (string), the DB relations use `category_id`
await supabase.from('products').upsert({
  id: productId,
  title: 'Product Name',
  description: 'Creative marketing description only. No specs here.',
  translations: {
    es: { title: 'Título en español', description: 'Descripción en español' },
    de: { title: 'Titel auf Deutsch', description: 'Beschreibung auf Deutsch' }
  },
  category: 'crewnecks',
  category_id: '3213a34b-0eeb-4195-8531-29e65f442384',
  pod_provider: 'printful',
  product_template_id: '411', // Cotton Heritage M2480 catalog ID
  provider_product_id: String(pfProductId), // Printful sync product ID
  base_price_cents: 4995,
  compare_at_price_cents: 6499, // Original price (strikethrough) — must be > base_price_cents
  images: [
    // v3: Fronts first (hero), then sleeves. No backs.
    { src: `https://.../mockups/slug/black-front.png?v=${ts}`, alt: 'Product Name - Black' },
    { src: `https://.../mockups/slug/navy-blazer-front.png?v=${ts}`, alt: 'Product Name - Navy Blazer' },
    { src: `https://.../mockups/slug/black-sleeve.png?v=${ts}`, alt: 'Product Name - Black - Sleeve' },
    { src: `https://.../mockups/slug/navy-blazer-sleeve.png?v=${ts}`, alt: 'Product Name - Navy Blazer - Sleeve' },
  ],
  product_details: {
    safety_information: '<p><strong>Manufacturer:</strong> Printful Inc., Latvia</p>...',
    material: '100% cotton face / 65% cotton, 35% polyester, 8.5 oz/yd²',
    care_instructions: 'Machine wash cold, inside out. Tumble dry low. Do not bleach. Iron on low heat, avoid print area.',
    print_technique: 'DTG (Direct-to-Garment)',
    manufacturing_country: 'Latvia',
    brand: 'SKAPARA',
    model: 'Cotton Heritage M2480',
    tier: 'PREMIUM',
    fit: 'Classic / Ribbed Crew Neck'
  },
  status: 'active'
})

// 2. Select colors via DESIGN-FIRST ANALYSIS (see MOCKUPS.md)
// Analyze the design's color palette BEFORE choosing garment colors.
// DO NOT default to Black — e.g., a black penguin design is invisible on a black shirt.
// Select 2-5 colors from the DARK EU palette that maximize contrast with the design.
const DARK_EU_PALETTE = [
  { color: 'Black', hex: '#101010', L: 16 },
  { color: 'Navy Blazer', hex: '#171f2c', L: 30 },
  { color: 'Charcoal Heather', hex: '#3a3a38', L: 58 },
  { color: 'Team Royal', hex: '#2d407d', L: 65 },
  { color: 'Vintage Black', hex: '#43413D', L: 65 },
  { color: 'Forest Green', hex: '#335231', L: 69 },
]

// Example: Nihilist Penguin (black penguin silhouette + white text)
// Black → EXCLUDED (penguin invisible on #101010)
// Navy Blazer → OK (L=30, dark but penguin silhouette visible)
// Charcoal Heather → BEST (L=58, great contrast for black elements)
// Team Royal → GOOD (blue background, black penguin pops)
// Vintage Black → GOOD (L=65, olive-gray, decent contrast)
// Forest Green → GOOD (green, black penguin visible)
const selectedColors = DARK_EU_PALETTE.filter(c => /* design-first analysis */ true)

const sizes = ['S', 'M', 'L', 'XL', '2XL', '3XL']

for (const { color, hex, variantId } of activeVariants) {
  for (const size of sizes) {
    await supabase.from('product_variants').upsert({
      product_id: productId,
      color,
      color_hex: hex,
      size,
      is_enabled: true,
      external_variant_id: String(variantId), // Printful catalog variant ID
      image_url: `https://.../mockups/slug/${colorSlug}-front.png?v=${ts}`
    })
  }
}

// 4. Disable light/no-EU color variants if they exist
await supabase
  .from('product_variants')
  .update({ is_enabled: false })
  .eq('product_id', productId)
  .in('color', ['White', 'Bone', 'Carbon Grey', 'Dusty Rose', 'Team Red',
                'Cardinal', 'Adobe', 'Latte', 'Khaki', 'Agave',
                'Light Pink', 'Lavender', 'Sky Blue'])

Step 6: GPSR Compliance

Every product MUST have GPSR data in product_details before going live. This is mandatory under EU Regulation 2023/988.

{
  "safety_information": "<p><strong>Manufacturer:</strong> Printful Inc., Gandijas Dambis 15, Riga, Latvia LV-1045</p><p><strong>Material:</strong> 100% cotton face / 65% cotton, 35% polyester</p><p><strong>Weight:</strong> 8.5 oz/yd² (288.2 g/m²)</p><p><strong>Compliance:</strong> REACH, OEKO-TEX Standard 100</p>",
  "material": "100% cotton face / 65% cotton, 35% polyester, 8.5 oz/yd² (288.2 g/m²)",
  "care_instructions": "Machine wash cold, inside out. Tumble dry low. Do not bleach. Iron on low heat, avoid print area.",
  "print_technique": "DTG (Direct-to-Garment)",
  "manufacturing_country": "Latvia",
  "brand": "SKAPARA"
}

Note: Charcoal Heather has a different composition (55% cotton, 45% polyester). If using that color, add a note in safety_information.

Workflow 2: Update Existing Product Branding

Use this when branding assets change or when adding branding to products that lack it.

Step 1: Get Current Product State

curl -s "https://api.printful.com/store/products/${SYNC_PRODUCT_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-PF-Store-Id: ${STORE}" | jq '.result.sync_variants[] | {id, name, files: [.files[].type]}'

Step 2: Render Updated Branding (if needed)

See BRANDING.md for ImageMagick render commands. Skip if using existing file IDs.

Step 3: Upload New Files (if needed)

Upload via POST /files. Save returned id.

Step 4: Update All Variants (Bulk)

curl -X PUT "https://api.printful.com/store/products/${SYNC_PRODUCT_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-PF-Store-Id: ${STORE}" \
  -H "Content-Type: application/json" \
  -d '{
    "sync_variants": [
      {
        "id": SYNC_VARIANT_ID_1,
        "files": [
          {"type": "default", "id": FRONT_DESIGN_FILE_ID},
          {"type": "sleeve_left", "id": 950653078}
        ]
      },
      ...repeat for all active variants...
    ]
  }'

Rate limit: delay(2000) between per-variant updates, delay(3000) between products.

Step 5: Regenerate Mockups

After branding update, regenerate mockups per MOCKUPS.md and update products.images[] in Supabase with fresh ?v=timestamp cache-busting.

Supabase Integration

Image URL Pattern

All mockup images stored in Supabase Storage under designs/mockups/{product-slug}/:

designs/mockups/{product-slug}/{color-slug}-front.png
designs/mockups/{product-slug}/{color-slug}-sleeve.png

Public URLs ALWAYS include cache-buster:

${SUPABASE_URL}/storage/v1/object/public/designs/mockups/{slug}/{color}-{placement}.png?v={timestamp}

Alt Text Convention (Critical for Frontend)

The buildVariantImageMap() function in product-detail-cache.ts parses alt text to map images to color variants:

Image order in products.images[]: Fronts (all colors) -> Sleeves (all colors). First image = hero for shop listing. No backs in v3 branding.

Known Issues & Gotchas

Variant Reference

See VARIANTS.md for the complete table of all 114 variants (19 colors x 6 sizes) with catalog variant IDs, hex codes, luminance values, EU availability, and status.

Branding Reference

See BRANDING.md for M2480-specific branding placements, vertical sleeve render commands, file IDs, and anti-patterns.

Mockup Reference

See MOCKUPS.md for M2480-specific mockup generation, template URL patterns, gallery structure, and rate limits.