printful-cc1717-production

name: Printful CC1717 Production description: >- Complete pipeline for Comfort Colors 1717 (catalog 586) SIGNATURE t-shirts on Printful. Covers product creation, variant management, branding placement, mockup generation, and Supabase integration. Use when creating CC1717 products, generating mockups, updating branding, or managing SIGNATURE tier t-shirts.

Printful CC1717 Production Pipeline

Full production pipeline for SKAPARA SIGNATURE tier t-shirts using the Comfort Colors 1717 blank on Printful. The CC1717 is a garment-dyed, heavyweight relaxed tee — the premium blank that defines the SKAPARA brand feel.

For Printify-based products (DTG design creation on Textildruck Europa P26), see the design-dtg skill instead.

Product Specifications

When to Use

• Create a new SIGNATURE tier t-shirt product on Printful
• Upload designs and apply SKAPARA branding to CC1717 products
• Generate mockups for CC1717 products
• Update branding (sleeve, back, label) on existing CC1717 products
• Manage CC1717 variant colors (enable/disable based on design compatibility)
• Update Supabase with CC1717 product data and mockup images

Placements & Canvas Sizes

All canvases at 150 DPI:

IMPORTANT: back and label_outside are mutually exclusive in Printful. We use back for SKAPARA wordmark.

Base Costs (Production)

Additional placement costs stack: front (included) + back (+$5.25) + sleeve_left (+$2.20) = $20.70 total extra per unit for S-L.

Color Selection

CORE DARK (Recommended for all SKAPARA designs)

These 9 colors are 100% safe for white/ghost text designs:

See VARIANTS.md for the complete 45-color catalog with all variant IDs, tier classifications, and EU availability notes.

Printful API Reference

Auth headers (ALL requests):

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

Rate limits:

• General API: ~120 req/min. Use delay(2000) between calls
• Mockup Generator: ~10 req/min. Use delay(10000) between tasks
• On 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.

Key endpoints:

Workflow 1: Create New CC1717 Product

Step 1: Upload Design to File Library

Design PNGs must be uploaded to Printful's File Library before they can be assigned to products. Printful does not accept external URLs directly in product creation — you must use a File Library id.

Upload pattern: Upload to Supabase Storage first (for permanent hosting), then POST the public URL to Printful.

# Upload to Supabase Storage
curl -X POST "${SUPABASE_URL}/storage/v1/object/designs/uploads/${FILENAME}" \
  -H "Authorization: Bearer ${SUPABASE_SERVICE_KEY}" \
  -H "apikey: ${SUPABASE_SERVICE_KEY}" \
  -H "Content-Type: image/png" \
  -H "x-upsert: true" \
  --data-binary "@${LOCAL_FILE_PATH}"

# Get public URL
PUBLIC_URL="${SUPABASE_URL}/storage/v1/object/public/designs/uploads/${FILENAME}"

# Upload to Printful File Library
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": "'${PUBLIC_URL}'",
    "filename": "'${FILENAME}'"
  }'

Response: { "result": { "id": 123456789, "type": "default", "preview_url": "..." } }

Save the id — this is the file_id used in all subsequent API calls.

Upload all placement assets:

1. Front design (1800x2400) → FRONT_FILE_ID
2. Sleeve S mark (600x525) → SLEEVE_FILE_ID (or reuse existing: 950410444)
3. Back wordmark (1800x2400) → BACK_FILE_ID (or reuse existing: 950410495)

Step 2: Create Sync Product

curl -X POST "https://api.printful.com/store/products" \
  -H "Authorization: Bearer ${PRINTFUL_API_TOKEN}" \
  -H "X-PF-Store-Id: ${PRINTFUL_STORE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "sync_product": {
      "name": "Product Name — CC1717",
      "thumbnail": "https://files.cdn.printful.com/files/.../preview.png"
    },
    "sync_variants": [
      {
        "variant_id": 15114,
        "retail_price": "34.99",
        "files": [
          { "type": "default", "id": FRONT_FILE_ID },
          { "type": "back", "id": BACK_FILE_ID },
          { "type": "sleeve_left", "id": SLEEVE_FILE_ID }
        ]
      },
      {
        "variant_id": 15115,
        "retail_price": "34.99",
        "files": [
          { "type": "default", "id": FRONT_FILE_ID },
          { "type": "back", "id": BACK_FILE_ID },
          { "type": "sleeve_left", "id": SLEEVE_FILE_ID }
        ]
      }
    ]
  }'

Key points:

• variant_id is the catalog variant ID from VARIANTS.md (NOT a sync variant ID)
• retail_price is the customer-facing price as a string (e.g., "34.99")
• files[].type maps to placement names: "default" = front, "back", "sleeve_left", "sleeve_right", "label_outside"
• Include ALL size variants for each color (S through 4XL = 7 variants per color)
• The files array is identical for all variants of the same color

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
• Use the Supabase Storage original URLs or Printful CDN preview URLs

Step 3: Set Variant Prices

Pricing by size (SIGNATURE tier retail):

CRITICAL: Set prices in Printful FIRST. The cron sync margin fixer overwrites prices if margin falls below 35%.

Step 4: Apply Branding

See BRANDING.md for the complete branding specification.

Quick summary:

• sleeve_left: S mark isotipo white, 32% of canvas (192px in 600px), centered — File ID 950410444
• back: SKAPARA wordmark white, 37% of canvas (666px in 1800px), y=150px — File ID 950410495

Step 5: Generate Mockups

See MOCKUPS.md for the complete mockup generation specification.

Quick summary:

curl -X POST "https://api.printful.com/mockup-generator/create-task/586" \
  -H "Authorization: Bearer ${PRINTFUL_API_TOKEN}" \
  -H "X-PF-Store-Id: ${PRINTFUL_STORE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "variant_ids": [15114],
    "format": "png",
    "width": 1000,
    "option_groups": ["Ghost"],
    "options": ["Front", "Left", "Back"],
    "files": [
      { "placement": "front", "image_url": "DESIGN_PREVIEW_URL", "position": { "area_width": 1800, "area_height": 2400, "width": 1800, "height": 2400, "top": 0, "left": 0 } },
      { "placement": "sleeve_left", "image_url": "SLEEVE_PREVIEW_URL", "position": { "area_width": 600, "area_height": 525, "width": 600, "height": 525, "top": 0, "left": 0 } },
      { "placement": "back", "image_url": "BACK_PREVIEW_URL", "position": { "area_width": 1800, "area_height": 2400, "width": 1800, "height": 2400, "top": 0, "left": 0 } }
    ]
  }'

Step 6: Download Mockups & Upload to Supabase Storage

Mockup S3 URLs expire in ~24h. Always download and re-upload to permanent storage:

const storagePath = `designs/mockups/${productSlug}/${colorSlug}-${placement}.png`
const ts = Math.floor(Date.now() / 1000)
const publicUrl = `${SUPABASE_URL}/storage/v1/object/public/designs/${storagePath}?v=${ts}`

Step 7: Update Supabase products Table

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

const images = [
  // Fronts first (hero images)
  { src: `https://.../mockups/slug/black-front.png?v=${ts}`, alt: 'Title - Black' },
  { src: `https://.../mockups/slug/pepper-front.png?v=${ts}`, alt: 'Title - Pepper' },
  // Backs
  { src: `https://.../mockups/slug/black-back.png?v=${ts}`, alt: 'Title - Black - Back' },
  // Sleeves
  { src: `https://.../mockups/slug/black-sleeve_left.png?v=${ts}`, alt: 'Title - Black - Sleeve' },
]

// 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' }
  },
  category_id: 'CATEGORY_UUID', // FK to categories table
  pod_provider: 'printful',
  product_template_id: '586', // Comfort Colors 1717 catalog ID
  provider_product_id: String(pfProductId), // Printful sync product ID
  base_price_cents: 3499,
  compare_at_price_cents: 6499, // Original price (strikethrough) — must be > base_price_cents
  images,
  product_details: {
    safety_information: GPSR_HTML,
    material: '100% Ring-Spun Cotton',
    care_instructions: 'Machine wash cold, inside out. Tumble dry low. Do not bleach. Do not iron directly on print.',
    print_technique: 'DTG (Direct-to-Garment)',
    manufacturing_country: 'Latvia',
    brand: 'SKAPARA',
    blank: 'Comfort Colors 1717',
    weight: '6.1 oz/yd',
    fit: 'Relaxed',
    treatment: 'Garment-dyed'
  },
  status: 'active'
})

// 2. Create product variants (dark colors only)
const sizes = ['S', 'M', 'L', 'XL', '2XL', '3XL', '4XL']

for (const { color, hex, variantId } of selectedColors) {
  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}`
    })
  }
}

Step 8: GPSR Compliance (MANDATORY for EU)

Every product MUST have GPSR data before going live. EU Regulation 2023/988.

<p><strong>Manufacturer:</strong> Printful Inc., Latvia</p>
<p><strong>Material:</strong> 100% Ring-Spun Cotton (Comfort Colors 1717, 6.1 oz/yd)</p>
<p><strong>Treatment:</strong> Garment-dyed</p>
<p><strong>Print technique:</strong> DTG (Direct-to-Garment) — water-based inks</p>
<p><strong>Care:</strong> Machine wash cold, inside out. Tumble dry low. Do not bleach. Do not iron directly on print.</p>
<p><strong>Compliance:</strong> REACH, OEKO-TEX Standard 100</p>

Store in products.product_details.safety_information (JSONB).

Workflow 2: Update Branding on Existing CC1717 Products

Step 1: Get Product & Extract Variant IDs

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

Step 2: Bulk Update with Branding Files

curl -X PUT "https://api.printful.com/store/products/${SYNC_PRODUCT_ID}" \
  -H "Authorization: Bearer ${PRINTFUL_API_TOKEN}" \
  -H "X-PF-Store-Id: ${PRINTFUL_STORE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "sync_variants": [
      {
        "id": SYNC_VARIANT_ID_1,
        "files": [
          { "type": "default", "id": FRONT_FILE_ID },
          { "type": "sleeve_left", "id": 950410444 },
          { "type": "back", "id": 950410495 }
        ]
      }
    ]
  }'

Note: When updating via bulk PUT, use the sync variant ID (from GET response), NOT the catalog variant ID.

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

Step 3: Regenerate Mockups

After branding update, regenerate all mockups to reflect the new sleeve/back assets. See MOCKUPS.md.

Known Issues & Gotchas

Description Rules

What goes in description (creative text only):

• Product context, design inspiration, target audience
• 2-3 sentences max, casual but smart tone
• Highlight the CC1717 premium feel: "garment-dyed heavyweight", "relaxed fit", "vintage wash"
• Must be translated to EN, ES, DE

What does NOT go in description:

• Material composition -> product_details.material
• Care instructions -> product_details.care_instructions
• Manufacturing info -> product_details.manufacturing_country
• Safety/compliance -> product_details.safety_information

Post-Creation Checklist

After creating a CC1717 product, verify:

• Product appears in shop with correct category (t-shirts)
• All enabled variant colors show in ProductCard color toggles
• Sizes correctly parsed (S, M, L, XL, 2XL, 3XL, 4XL)
• Price is correct per size tier (not overridden by margin fixer)
• Mockup images load for all placements (front, back, sleeve)
• GPSR safety information stored in product_details
• Description is clean (no HTML tags, max 2000 chars)
• Light colors (L > 50) disabled if design uses white/ghost text
• Alt text follows pattern: "Title - Color", "Title - Color - Back", "Title - Color - Sleeve"
• Images ordered: all fronts first, then backs, then sleeves
• Cache-buster ?v=timestamp appended to all image URLs