GET /v1/catalog — sync catalog for Italy
Pull country-localised SKUs with MOQ, lead times, price tiers. Cursor pagination, If-Modified-Since for delta sync, Milano-hub availability flags.
Pagination & deltas
GET /v1/catalog?country=Italy&cursor=…&limit=200 (max 500). Each page returns { data:[…], next_cursor }. Use If-Modified-Since header for delta sync — server returns 304 when nothing changed. ETag also supported. Full catalog typically ~12k SKUs for Italy.
Object shape
Each catalog item: { sku, name_i18n:{en, it}, category_path, moq, lead_time_days, base_price_cents (EUR, excl IVA), iva_rate:22%, weight_grams, hub:'Milano', sustainability:{recycled_pct, gots_certified}, image_urls[], variants[] }. All prices pre-tax; client applies IVA 22% or uses the explicit field.
Filtering & search
Filters: ?category=apparel&min_moq=50&max_lead_days=15&hub=Milano&certified=gots. Full-text search via ?q=… (matches name_i18n, sku, tags). All filter params combinable. Server-side limit of 500 results per request keeps p95 latency under 250 ms.
FAQ
How often does the catalog change?
Daily price updates (00:30 UTC), weekly SKU additions (Mon 06:00 UTC). Use webhook event catalog.updated for push-style sync.
Can I get product images?
image_urls[] field returns CDN URLs at original resolution; append ?w=800 for resized variants (server-side image processing).
Are prices VAT-inclusive?
No — base_price_cents excludes IVA. Apply iva_rate (typically 22%) for end-customer pricing in Italy.
What about MOQ enforcement?
moq field is the absolute minimum per order line. Submitting below it returns 400 min_qty_violation. Some SKUs have moq_increment for step quantities.
Can I filter by certification?
Yes — ?certified=gots,fairwear,iso14001 returns only SKUs with all listed certifications. Combine with ?sustainability_min_recycled_pct=30 for stricter filters.