🛍️ Etsy Open API v3 — Handmade & Vintage Products (BYOC)

🔗 View on Apify Store | 🇺🇸 English | 🇧🇷 Português

Query Etsy Open API v3 for active handmade and vintage product listings across 8+ countries. BYOC (Bring Your Own Credentials) model — you provide your free personal Etsy API keystring, we handle the rest. Anti-bot-immune (official API), ~98% margin, predictable cost.

✨ Features

• Official Etsy Open API v3 — no HTML scraping, no anti-bot blocks
• 8 country filters — US, UK, DE, FR, CA, AU, ES, IT + ANY
• Keyword search with sort by relevance/price/date
• Price range filter (minPrice / maxPrice)
• Auto-pagination up to 500 results (100 per page hard cap by Etsy)
• Rich output — tags, materials, who_made, when_made, num_favorers, views, taxonomy_id, style, shop info
• Rate-limit aware — built-in 250ms pause (under 5 QPS personal limit)
• NEVER 0 ITEMS guard — actor fails loudly with diagnosis instead of silently succeeding

🔑 BYOC setup (one-time, free, ~5 min)

1. Sign in at https://www.etsy.com/developers
2. Click Create a New App (or use an existing one)
3. After approval (1-7 days for personal review), copy your Keystring from "Your Apps"
4. Paste the Keystring in the actor input under Etsy API Keystring (BYOC)

Important: New keys arrive with status "Pending Personal Approval". The actor will throw [ETSY_AUTH] 403 API key not found or not active until Etsy reviewers activate it. This is normal — wait for the email.

Limits: Free tier = 5 QPS / 5K queries per day. Plenty for most affiliate research workflows.

📥 Input

Parameter	Type	Required	Default	Description
keystring	string (secret)	Yes	—	Your Etsy API keystring (see BYOC setup above)
searchQuery	string	Yes	—	Search term (e.g. "handmade jewelry")
country	enum	No	US	Origin country filter (US/UK/DE/FR/CA/AU/ES/IT/ANY)
sortOn	enum	No	score	Sort dimension: score/price/created/updated
sortOrder	enum	No	desc	asc or desc
minPrice	integer	No	0	Minimum price (in country currency, 0 = no filter)
maxPrice	integer	No	0	Maximum price (0 = no filter)
maxResults	integer	No	24	Total listings to fetch (1-500)

Input example

{
  "keystring": "your_etsy_keystring_here",
  "searchQuery": "wedding ring rose gold",
  "country": "US",
  "minPrice": 100,
  "maxPrice": 1000,
  "maxResults": 50
}

📤 Output

Each record contains:

{
  "listingId": 1234567890,
  "title": "Handmade Rose Gold Wedding Ring — Custom Engraving",
  "description": "Beautiful handmade ring crafted in our small studio…",
  "url": "https://www.etsy.com/listing/1234567890/...",
  "price": 245.0,
  "currency": "USD",
  "state": "active",
  "whoMade": "i_did",
  "whenMade": "made_to_order",
  "isSupply": false,
  "isCustomizable": true,
  "isDigital": false,
  "quantity": 999,
  "views": 4521,
  "numFavorers": 138,
  "tags": ["wedding ring", "rose gold", "engagement"],
  "materials": ["14k rose gold", "diamond"],
  "styleTags": ["minimalist"],
  "taxonomyId": 1234,
  "originCountryIso": "US",
  "shop": {
    "shopId": 5555,
    "shopName": "BohoJewelryStudio",
    "url": "https://www.etsy.com/shop/BohoJewelryStudio"
  },
  "thumbnail": "https://i.etsystatic.com/.../il_570xN.jpg",
  "createdAt": 1715000000,
  "updatedAt": 1715800000,
  "countryFilter": "US",
  "source": "etsy-open-api-v3"
}

💰 Pricing

Pay-per-event (PPE): only charged when the actor returns a real listing. Zero results → zero charge. Anti-bot blocks are impossible here (official API).

🚀 Use cases

• Affiliate research — surface high-favorers handmade niches before saturation
• Price intelligence — track competitor pricing in handmade/vintage verticals
• Trend discovery — sort by created desc + score to spot rising listings
• Catalog import — seed your own e-commerce or comparison site
• SEO content — extract tags + materials for long-tail keyword research

⚠️ Common errors

Error	Cause	Fix
[ETSY_AUTH] 401 Unauthorized	Keystring invalid or expired	Verify at https://www.etsy.com/developers/your-apps
[ETSY_AUTH] 403 API key not found or not active	Key still Pending Personal Approval	Wait 1-7 days for Etsy review
[ETSY_RATE] 429 Too Many Requests	Hit 5 QPS / 5K QPD personal limit	Wait or upgrade Etsy app tier
[FAIL] Zero listings returned	Filter too restrictive	Try country: "ANY" or broader keyword

🔒 Privacy

Your keystring is passed directly to api.etsy.com over HTTPS. We never store, log, or proxy it through our servers. Mark the input field as secret in Apify Console.

📚 Related actors

• Rakuten Affiliate Merchants — Rakuten API (BYOC)
• CJ Affiliate Products — Commission Junction GraphQL (BYOC)
• Impact.com Affiliate API — Impact.com REST (BYOC)
• Awin Multi-Merchant — Awin Publisher API (BYOC)

🆕 Changelog

• v2.0 (2026-05-14): Major refactor from Playwright HTML scraping (HTTP 403 anti-bot blocked all attempts) to Etsy Open API v3 (BYOC). 98% margin, anti-bot-immune, ToS-compliant. Output adds tags, materials, whoMade, views, numFavorers, taxonomyId.
• v1.1 (2026-05-14): Playwright + RESIDENTIAL fingerprints attempted; Etsy Akamai still 403 → deprecated.
• v1.0 (2026-05-12): Initial CheerioCrawler release.

---

Português

🛍️ Etsy Open API v3 — Produtos Artesanais e Vintage (BYOC)

Consulta a API oficial Etsy Open API v3 para listings de produtos artesanais e vintage ativos em 8+ países. BYOC (Bring Your Own Credentials) — você fornece sua keystring pessoal grátis do Etsy, nós cuidamos do resto. Imune a anti-bot (API oficial), margem ~98%, custo previsível.

Setup BYOC (uma vez, grátis, ~5 min)

1. Entre em https://www.etsy.com/developers
2. Crie um app (ou use um existente)
3. Após aprovação (1-7 dias para revisão pessoal), copie sua Keystring em "Your Apps"
4. Cole no campo Etsy API Keystring (BYOC) do input do actor

Importante: novas chaves chegam com status "Pending Personal Approval". O actor retorna [ETSY_AUTH] 403 API key not found or not active até o Etsy ativar. Aguarde o email.

Limites: tier grátis = 5 req/seg / 5K req/dia. Suficiente para a maioria dos casos de uso.