printful-yupoong-6089m-embroidery-wool-blend-snapback

name: Printful Yupoong 6089M Embroidery Wool Blend Snapback description: Complete pipeline for Yupoong 6089M (catalog 99) embroidered wool blend snapback on Printful. Covers embroidery product creation with 5 placements (front, front_large, back, left, right), thread color selection, variant management, mockup generation, and Supabase integration. Use when creating embroidered Yupoong 6089M snapback products, generating mockups, updating branding, or managing snapback headwear. 18 colors (21 variants) including two-tone combinations — EU Latvia fulfillment. Options: unlimited_color +3.25EUR, 3D puff +1.50EUR.

Printful Yupoong 6089M Embroidery — Complete Pipeline

Product Overview

Instructions

Embroidery Specs — Yupoong 6089M

• Thread colors: 15 standard colors available, max 6 per design
• Unlimited color: CMYK polyester thread, gradient-capable (+3.25 EUR per placement)
• 3D Puff: Available (+1.50 EUR) — structured high-profile cap supports 3D puff well
• Min text height: 5mm / 0.25"
• Min line width: 1.5mm
• File format: PNG @300dpi preferred
• Stitch count: Max ~15,000 stitches standard

Pre-requisitos

1. Cuenta Printful con API token y Store ID (17795695 — Skapara)
2. Supabase con tablas products y product_variants
3. Diseños de bordado en formato PNG @300dpi
4. Diseños deben respetar limites de colores de hilo (max 6 standard, or unlimited_color)

Placements Disponibles

NOTE: embroidery_front and embroidery_front_large share the same printfile (PF#478). Use ONE of them, not both.

NOTE: Side placements (left/right) use PF#706 which is SQUARE (675x675) — different from other hats that use PF#76 (600x300). Design accordingly.

Branding Rules — Snapback

• Front: Main design (logo, icon, text) — this hat has the LARGEST front canvas of any hat (1890x765)
• Back (where used): S mark or skapara.com — white thread on dark hats, dark thread on light hats
• Left/Right sides (where used): Mini S mark — square canvas (675x675) allows circular/square designs
• NEVER copy the front design to other placements — each position has its own design

Pipeline Completo — 10 Steps

Paso 1: Disenar bordados

Design embroidery files for each placement you plan to use. Recommended config:

Standard config (2 placements — front + back):

Premium config (4 placements — front + back + sides):

Paso 2: Renderizar PNGs @300dpi

# Front design (largest hat front — 6.30"x2.55")
magick -density 300 -background transparent design-front.svg -resize 1890x765! design-front.png

# Back design
magick -density 300 -background transparent design-back.svg -resize 600x300! design-back.png

# Side designs (SQUARE — different from other hats)
magick -density 300 -background transparent design-side.svg -resize 675x675! design-side.png

Each PNG must match exactly the canvas dimensions of its placement.

Paso 3: Subir PNGs a Supabase Storage (URL publica)

Printful NO acepta data URLs ni base64. Necesita una URL publica accesible.

await supabase.storage.from('designs').upload(
  'embroidery-sources/6089m-product-name/front.png',
  pngBuffer,
  { contentType: 'image/png', upsert: true }
);
const publicUrl = `${SB_URL}/storage/v1/object/public/designs/embroidery-sources/6089m-product-name/front.png`;

Paso 4: Subir a Printful File Library

const result = await pf('/files', {
  method: 'POST',
  body: JSON.stringify({
    url: publicUrl,
    filename: '6089m-product-embroidery_front.png',
  }),
});
const fileId = result.result.id;

Rate limit: delay(3000) between uploads.

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.

API Auth headers (ALL calls):

Authorization: Bearer ${PRINTFUL_API_TOKEN}
User-Agent: POD-AI-Store/1.0
X-PF-Store-Id: 17795695          // Skapara store — NEVER 17595620
Content-Type: application/json

Paso 5: Crear Sync Product en Printful

const product = await pf('/store/products', {
  method: 'POST',
  body: JSON.stringify({
    sync_product: {
      name: 'Product Name — Snapback',
      thumbnail: publicUrlFront,
    },
    sync_variants: variants.map(v => ({
      variant_id: v.variant_id,
      retail_price: '29.99',
      is_enabled: true,
      files: [
        { type: 'embroidery_front', id: frontFileId },
        { type: 'embroidery_back', id: backFileId },
      ],
      options: [
        { id: 'thread_colors_front', value: ['#FFFFFF', '#000000'] },
        { id: 'thread_colors_back', value: ['#FFFFFF'] },
      ],
    })),
  }),
});

See VARIANTS.md for the complete variant_ids table (18 colors, 21 variants).

Thread colors format: thread_colors_<placement_without_embroidery_prefix>:

thread_colors_front        (NOT thread_colors_embroidery_front)
thread_colors_front_large  (NOT thread_colors_embroidery_front_large)
thread_colors_back         (NOT thread_colors_embroidery_back)
thread_colors_left         (NOT thread_colors_embroidery_left)
thread_colors_right        (NOT thread_colors_embroidery_right)

Thread color selection for hat colors (18 API-verified colors):

• Dark hats (Black, Dark Grey, Dark Navy, Navy, Maroon, Spruce, Green Camo): WHITE (#FFFFFF) or light threads
• Light hats (Silver, Heather Grey, Natural/Black, White): BLACK (#000000) or dark threads
• Two-tone hats (Black/Neon Pink, Black/Red, Black/Silver, Black/Teal, Heather/Black): Match thread to the front panel color

Paso 6: GPSR — Supabase product_details

NOTE: The GPSR API endpoint (/store/products/{id}/gpsr.json) returns 404 for embroidery products. GPSR is managed in Supabase product_details.safety_information.

<p><strong>Manufacturer:</strong> Printful Latvia SIA, Matrozu iela 15, LV-1048, Riga, Latvia</p>
<p><strong>Material:</strong> 80% acrylic, 20% wool</p>
<p><strong>Print technique:</strong> Embroidery</p>
<p><strong>Care:</strong> Spot clean only.</p>
<p><strong>Compliance:</strong> REACH, OEKO-TEX Standard 100</p>

NOTE for Green Camo variant: Material is 60% cotton, 40% polyester — different from the standard blend. Consider noting this in product_details or as a variant-level note.

Paso 7: Crear producto en Supabase

await supabase.from('products').insert({
  id: crypto.randomUUID(),
  title: 'Product Name',
  description: 'Creative marketing description EN — wool blend snapback with embroidered design',
  category: 'snapbacks',
  base_price_cents: 2999,
  compare_at_price_cents: 3499,
  currency: 'EUR',
  status: 'active',
  pod_provider: 'printful',
  provider_product_id: String(pfProductId),
  product_template_id: '99',
  category_id: '<snapbacks-uuid>',
  translations: {
    es: { title: 'Product Name', description: 'Descripcion creativa ES...' },
    de: { title: 'Product Name', description: 'Kreative Beschreibung DE...' },
  },
  product_details: {
    brand: 'SKAPARA',
    model: 'Yupoong 6089M',
    material: '80% acrylic, 20% wool',
    print_technique: 'Embroidery',
    manufacturing_country: 'LV',
    safety_information: '...GPSR HTML from Paso 6...',
  },
});

Paso 8: Crear variantes en Supabase

IMPORTANT: La tabla product_variants requiere campo title (NOT NULL).

// 18 colors (21 variants), each color with one size
for (const [color, variantId] of Object.entries(VARIANT_IDS)) {
  variants.push({
    product_id: PRODUCT_UUID,
    title: `Product Name / ${color} / One size`,
    color,
    size: 'One size',
    price_cents: 2999,
    is_enabled: true,
    is_available: true,
    external_variant_id: String(variantId),
  });
}

Paso 9: Mockups

Generate mockups for each color (or a representative subset). Snapbacks typically show front, side, and back views.

With 18 colors, consider generating mockups for the most popular 8-10 colors and adding the rest later.

Paso 10: Actualizar imagenes en Supabase

Alt text uses hyphen (-), NOT em dash — required by buildImageMap() in the API.

await supabase.from('products').update({
  images: [
    { src: '.../black-front.png', alt: 'Product Name - Black' },
    { src: '.../black-side.png', alt: 'Product Name - Black - Side' },
    { src: '.../dark-navy-front.png', alt: 'Product Name - Dark Navy' },
    { src: '.../dark-navy-side.png', alt: 'Product Name - Dark Navy - Side' },
    // ... more colors
  ],
}).eq('id', productId);

Pricing Breakdown

1 placement (front only)

2 placements (front + back)

4 placements (front + back + sides)

With unlimited_color (+3.25 EUR per placement): Add to each placement that uses it. With 3D puff (+1.50 EUR): Add to front placement if 3D effect desired.

Known Issues

1. Printful NO acepta data URLs: The /files endpoint rejects base64/data URLs. Error: "file URL is not a valid URL". ALWAYS upload to Supabase Storage first and use the public URL.
2. GPSR endpoint 404 for embroidery: GET /store/products/{id}/gpsr.json returns 404. GPSR must be managed directly in Supabase product_details.safety_information.
3. thread_colors obligatorio: Without specifying thread colors, Printful uses defaults that may not match the design. ALWAYS specify thread_colors_<placement> in options.
4. thread_colors ID format: The option ID does NOT carry the embroidery_ prefix. Correct: thread_colors_front, incorrect: thread_colors_embroidery_front.
5. product_variants.title NOT NULL: Supabase requires title field in product_variants. Use format "ProductName / Color / One size".
6. embroidery_front vs embroidery_front_large: Both use PF#478 and same canvas. They are aliases — use ONE, not both.
7. 18 colors, 21 variants: API-verified as of 2026-03-04. 3 two-tone combos from original catalog (Heather Grey/Navy, Heather Grey/Red, Navy/Red) are no longer available. White was added. Some colors may have multiple variants (total 21). Consider which colors to enable initially.
8. Green Camo material difference: Green Camo is 60% cotton / 40% polyester (NOT 80% acrylic / 20% wool). This may affect embroidery quality.
9. Two-tone color names: Colors like "Black/Neon Pink" have slashes — handle carefully in slug generation and alt text.
10. Square side placements: Left/Right use PF#706 (675x675) — SQUARE, unlike other hats that use PF#76 (600x300 rectangular). Design files must be square.
11. Rate limits: Use delay(1500-2000) between API calls. Store ID header required for v1 endpoints.
12. Store ID: ALWAYS use 17795695 (Skapara). NEVER use 17595620 (different store).