printful-g18600-zip-hoodie-production

name: Printful G18600 Zip Hoodie Production description: >- Complete pipeline for Gildan 18600 (catalog 692) zip hoodies on Printful. Covers product creation, variant management, branding placement, mockup generation, and Supabase integration. Use when creating G18600 zip hoodie products, generating mockups, updating branding, or managing zip hoodie products. ONLY zip hoodie with EU fulfillment.

Printful G18600 Zip Hoodie Production Pipeline — STANDARD Tier

Full production pipeline for SKAPARA zip hoodies on the Gildan 18600 blank via Printful API. This is the STANDARD tier zip hoodie — the only zip hoodie blank with EU fulfillment.

For premium t-shirts (MC1087), see the printful-mc1087 skill. For signature t-shirts (CC1717), see the printful-cc1717 skill. For Printify-based products (legacy DTG on P26), see the design-dtg skill.

Product Specifications

Key differentiator: This is a ZIP hoodie — the front canvas is 2250x1500px LANDSCAPE because the zipper splits the design down the center. Designs MUST account for the center zip line. Also has the biggest size range (S-5XL, 8 sizes).

Placements & Dimensions

All canvases at 150 DPI unless noted:

CRITICAL DIFFERENCES vs other blanks:

• Front is 2250x1500 LANDSCAPE (NOT 1800x2400 portrait like t-shirts). The zipper runs down the center!
• NO label_inside — only label_outside at 600x600
• label_outside is 600x600 (larger than MC1087/CC1717's 450x450)
• Sleeve is 450x1800 VERTICAL (not 600x525 horizontal like MC1087)
• back and label_outside are mutually exclusive in Printful. We use back for SKAPARA wordmark.

Base Costs

EU colors cost ~$1.75 more ($24.25 for S-XL).

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

• S-XL: $22.50 + $5.25 + $2.20 = $29.95 (non-EU) / $31.70 (EU)

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-2250x1500.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-2250x1500.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 G18600 Product

Step 1: Prepare Design Files

Design the main front canvas at 2250x1500px LANDSCAPE. The zipper splits the design down the center — either:

1. Avoid the center — use left-chest or right-chest placement
2. Design across the zip — create a split design that works when the zipper separates the two halves

Render branding assets per BRANDING.md.

Required files:

1. Front design — 2250x1500 PNG (LANDSCAPE — unique to zip hoodies!)
2. Sleeve left — 450x1800 PNG (S mark, vertical — needs new render for G18600!)
3. Back wordmark — 1800x2400 PNG (SKAPARA wordmark, can reuse file_id: 950410495)

NOTE: The sleeve canvas for G18600 is 450x1800 (vertical), NOT 600x525 (horizontal) like MC1087. A new sleeve branding file must be rendered. See BRANDING.md.

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 back branding file is already uploaded:

• back: 950410495 (same wordmark as MC1087/CC1717)

The sleeve branding file needs a NEW upload for the 450x1800 vertical canvas. See BRANDING.md for render instructions.

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": 17295,
        "retail_price": "59.95",
        "files": [
          {"type": "default", "id": FRONT_DESIGN_FILE_ID},
          {"type": "sleeve_left", "id": SLEEVE_LEFT_FILE_ID},
          {"type": "back", "id": 950410495}
        ]
      },
      {
        "variant_id": 17296,
        "retail_price": "59.95",
        "files": [
          {"type": "default", "id": FRONT_DESIGN_FILE_ID},
          {"type": "sleeve_left", "id": SLEEVE_LEFT_FILE_ID},
          {"type": "back", "id": 950410495}
        ]
      }
    ]
  }'

IMPORTANT: Include ALL active EU variants for the colors selected via design-first analysis (see MOCKUPS.md). For example, 3 colors x 8 sizes = 24 variants. 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.

Step 4: Generate Mockups

Follow MOCKUPS.md workflow. Generate Ghost mockups for all active dark colors with Front, Left, and Back views.

Step 5: Update Supabase

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

// 1. Create or update product in Supabase
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' }
  },
  base_price_cents: 5995,
  compare_at_price_cents: 6499, // Original price (strikethrough) — must be > base_price_cents
  images: [
    { src: `https://.../mockups/slug/black-front.png?v=${ts}`, alt: 'Product Name - Black' },
    { src: `https://.../mockups/slug/navy-front.png?v=${ts}`, alt: 'Product Name - Navy' },
    { src: `https://.../mockups/slug/black-back.png?v=${ts}`, alt: 'Product Name - Black - Back' },
    { src: `https://.../mockups/slug/navy-back.png?v=${ts}`, alt: 'Product Name - Navy - Back' },
    { src: `https://.../mockups/slug/black-left.png?v=${ts}`, alt: 'Product Name - Black - Sleeve' },
  ],
  product_details: {
    safety_information: '<p><strong>Manufacturer:</strong> Printful Inc., Latvia</p>...',
    material: '50% cotton, 50% polyester, 8 oz/yd2 (271 g/m2)',
    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: 'Gildan 18600',
    tier: 'STANDARD',
    fit: 'Regular / Zip Hoodie'
  },
  pod_provider: 'printful',
  product_template_id: '692',
  provider_product_id: String(pfProductId),
  status: 'active'
})

// 2. Create product variants (only EU dark colors)
// Select colors via DESIGN-FIRST ANALYSIS (see MOCKUPS.md)
// Analyze the design's color palette BEFORE choosing garment colors.
const DARK_EU_PALETTE = [
  { color: 'Black', hex: '#0b0b0b', L: 11 },
  { color: 'Navy', hex: '#15263c', L: 35 },
  { color: 'Dark Heather', hex: '#3c3d44', L: 61 },
  { color: 'Royal', hex: '#1d57a5', L: 79 },
]
const selectedColors = DARK_EU_PALETTE.filter(c => /* design-first analysis */ true)
const sizes = ['S', 'M', 'L', 'XL', '2XL', '3XL', '4XL', '5XL']

for (const { color, hex } of selectedColors) {
  // NOTE: Dark Heather only has 6 sizes (S-3XL), no 4XL/5XL
  const colorSizes = color === 'Dark Heather'
    ? sizes.filter(s => !['4XL', '5XL'].includes(s))
    : sizes
  for (const size of colorSizes) {
    await supabase.from('product_variants').upsert({
      product_id: productId,
      color,
      color_hex: hex,
      size,
      is_enabled: true,
      image_url: `https://.../mockups/slug/${colorSlug}-front.png?v=${ts}`,
      external_variant_id: String(variantId), // Printful catalog variant ID
    })
  }
}

// 3. Disable light color variants if they exist
await supabase
  .from('product_variants')
  .update({ is_enabled: false })
  .eq('product_id', productId)
  .in('color', ['Sport Grey', 'Carolina Blue', 'White', 'Ash', 'Irish Green'])

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> 50% cotton, 50% polyester</p><p><strong>Weight:</strong> 8 oz/yd2 (271 g/m2)</p><p><strong>Compliance:</strong> REACH, OEKO-TEX Standard 100</p><p><strong>Features:</strong> Air-jet spun yarn for reduced piling, metal zipper, unlined hood</p>",
  "material": "50% cotton, 50% polyester, 8 oz/yd2 (271 g/m2)",
  "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"
}

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. The G18600 requires a unique sleeve render (450x1800 vertical).

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": SLEEVE_LEFT_FILE_ID},
          {"type": "back", "id": 950410495}
        ]
      },
      ...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}-back.png
designs/mockups/{product-slug}/{color-slug}-left.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) -> Backs (all colors) -> Sleeves. First image = hero for shop listing.

Known Issues & Gotchas

Variant Reference

See VARIANTS.md for the complete table of all 94 variants across 14 colors with catalog variant IDs, hex codes, sizes, EU availability, and status.

Branding Reference

See BRANDING.md for G18600-specific branding placements, render commands (including the unique landscape front and vertical sleeve), and anti-patterns.

Mockup Reference

See MOCKUPS.md for G18600-specific mockup generation, template structure, gallery layout, and rate limits.