printful-beechfield-b682-embroidery-corduroy-hat

name: Printful Beechfield B682 Embroidery Corduroy Hat description: Complete pipeline for Beechfield B682 (catalog 532) embroidered corduroy hat on Printful. Covers embroidery product creation with 4 placements (front, back, left, right), thread color selection, variant management, mockup generation, and Supabase integration. Use when creating embroidered Beechfield B682 corduroy hat products, generating mockups, updating branding, or managing corduroy hat headwear. 4 colors (Black, Camel, Dark Olive, Oxford Navy) — EU Latvia fulfillment. Options: unlimited_color +3.25EUR. Premium corduroy material.

Printful Beechfield B682 Embroidery — Complete Pipeline

Product Overview

Instructions

Embroidery Specs — Beechfield B682

• Thread colors: 15 standard colors available, max 6 per design
• Unlimited color: CMYK polyester thread, gradient-capable (+3.25 EUR per placement)
• 3D Puff: NOT recommended — soft unstructured crown does not hold 3D puff reliably
• 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: No embroidery_front_large placement on this product — only standard embroidery_front.

NOTE: Front canvas (PF#78, 1200x525) is SMALLER than Otto Cap (PF#75, 1650x600) and Yupoong (PF#478, 1890x765). Design accordingly.

Branding Rules — Corduroy Hat

• Front: Main design (logo, icon, text) — compact canvas (4.00"x1.75"), keep designs clean
• Back (where used): S mark or skapara.com — white thread on dark hats (Black, Dark Olive, Oxford Navy), dark thread on light hats (Camel)
• Left/Right sides (where used): Mini S mark
• 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 (3-4 placements — front + back + sides):

Paso 2: Renderizar PNGs @300dpi

# Front design (smaller canvas than other hats — 4.00"x1.75")
magick -density 300 -background transparent design-front.svg -resize 1200x525! design-front.png

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

# Side designs (if used)
magick -density 300 -background transparent design-side.svg -resize 600x300! 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/b682-product-name/front.png',
  pngBuffer,
  { contentType: 'image/png', upsert: true }
);
const publicUrl = `${SB_URL}/storage/v1/object/public/designs/embroidery-sources/b682-product-name/front.png`;

Paso 4: Subir a Printful File Library

const result = await pf('/files', {
  method: 'POST',
  body: JSON.stringify({
    url: publicUrl,
    filename: 'b682-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 — Corduroy Hat',
      thumbnail: publicUrlFront,
    },
    sync_variants: variants.map(v => ({
      variant_id: v.variant_id,
      retail_price: '34.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.

Thread colors format: thread_colors_<placement_without_embroidery_prefix>:

thread_colors_front        (NOT thread_colors_embroidery_front)
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:

• Dark hats (Black, Dark Olive, Oxford Navy): WHITE (#FFFFFF) or light threads
• Light hats (Camel): BLACK (#000000) or dark threads — corduroy texture adds visual interest

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> 100% cotton corduroy, cotton twill sweatband</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>

Paso 7: Crear producto en Supabase

await supabase.from('products').insert({
  id: crypto.randomUUID(),
  title: 'Product Name',
  description: 'Creative marketing description EN — premium corduroy hat with embroidered design',
  category: 'caps',
  base_price_cents: 3499,
  compare_at_price_cents: 3999,
  currency: 'EUR',
  status: 'active',
  pod_provider: 'printful',
  provider_product_id: String(pfProductId),
  product_template_id: '532',
  category_id: '<caps-uuid>',
  translations: {
    es: { title: 'Product Name', description: 'Descripcion creativa ES...' },
    de: { title: 'Product Name', description: 'Kreative Beschreibung DE...' },
  },
  product_details: {
    brand: 'SKAPARA',
    model: 'Beechfield B682',
    material: '100% cotton corduroy',
    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).

const colors = ['Black', 'Camel', 'Dark Olive', 'Oxford Navy'];

for (const color of colors) {
  variants.push({
    product_id: PRODUCT_UUID,
    title: `Product Name / ${color} / One size`,
    color,
    size: 'One size',
    price_cents: 3499,
    is_enabled: true,
    is_available: true,
    external_variant_id: String(VARIANT_IDS[color]),
  });
}

Paso 9: Mockups

Generate mockups for each color. Corduroy hats show front and side views well — the texture is visible.

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: '.../camel-front.png', alt: 'Product Name - Camel' },
    { src: '.../camel-side.png', alt: 'Product Name - Camel - Side' },
    { src: '.../dark-olive-front.png', alt: 'Product Name - Dark Olive' },
    { src: '.../dark-olive-side.png', alt: 'Product Name - Dark Olive - Side' },
    { src: '.../oxford-navy-front.png', alt: 'Product Name - Oxford Navy' },
    { src: '.../oxford-navy-side.png', alt: 'Product Name - Oxford Navy - Side' },
  ],
}).eq('id', productId);

Pricing Breakdown

1 placement (front only)

2 placements (front + back) — Recommended

4 placements (front + back + sides)

With unlimited_color (+3.25 EUR per placement): Add to each placement that uses it.

NOTE: B682 has a higher base cost (16.95 EUR) than other hats. Pricing should reflect the premium corduroy material.

Known Issues

1. Printful NO acepta data URLs: The /files endpoint rejects base64/data URLs. ALWAYS upload to Supabase Storage first.
2. GPSR endpoint 404 for embroidery: GET /store/products/{id}/gpsr.json returns 404. GPSR must be managed in Supabase.
3. thread_colors obligatorio: ALWAYS specify thread_colors_<placement> in options.
4. thread_colors ID format: Correct: thread_colors_front, incorrect: thread_colors_embroidery_front.
5. product_variants.title NOT NULL: Use format "ProductName / Color / One size".
6. No front_large placement: Unlike Otto Cap and Yupoong, B682 does NOT have embroidery_front_large. Only embroidery_front with PF#78 (1200x525).
7. Smaller front canvas: PF#78 is 1200x525 (4.00"x1.75") — smaller than PF#75 (5.50"x2.00") and PF#478 (6.30"x2.55"). Design files from other hats need resizing.
8. Premium material pricing: Base cost 16.95 EUR is significantly higher than other hats. Price retail accordingly to maintain margins.
9. Corduroy texture: The wale texture of corduroy can affect how embroidery looks — bold, simple designs work best.
10. Unstructured crown: Soft crown means 3D puff embroidery is NOT recommended — flat embroidery only.
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).