How to Scrape Etsy Product Listings: Products, Prices, and Shops
Use Etsy Open API v3 to collect authorized listing, price, and shop data while avoiding prohibited screen scraping.

Direct answer: use Etsy Open API v3 to retrieve authorized listing and shop data. Do not copy Etsy HTML or automate a browser against Etsy pages. Etsy’s developer documentation states that applications must not sidestep the API and that screen scraping is not allowed. The API gives you structured fields for listings, while OAuth controls private and write operations.
This guide shows how to choose an Etsy access tier, authenticate, retrieve products and shops, handle prices and variations correctly, paginate safely, and build a reliable data pipeline. It also explains what to do when you need screenshots of your own permitted pages without maintaining browser automation.
1. What “scraping Etsy” should mean
For an authorized integration, “scraping Etsy” means making HTTPS requests to Etsy’s documented API and storing the response fields your application is allowed to use. It does not mean downloading search-result HTML, parsing embedded JSON from storefront pages, rotating proxies, or driving a headless browser around bot checks.
Etsy describes a listing as a page containing a product for sale. Depending on your application’s access level, API access can cover one shop or marketplace data. Every request uses HTTPS and an x-api-key. Private data and write operations additionally require OAuth 2.0 with the scopes required by the endpoint. See Etsy’s developer documentation and API Terms of Use before shipping an integration.
2. Choose the correct Etsy access tier
| Tier | Use it when | Typical data scope |
|---|---|---|
| Seller App | You need your own shop’s listings, orders, inventory, or related data. | One seller’s shop, with seller-authorized access. |
| Personal App | You are building beyond one shop at limited scale. | Broader application use, subject to Etsy approval and terms. |
| Commercial Access | Your product serves other sellers or needs broader marketplace capability. | Commercial application, manual review, compliant home page, caching controls, and clear distinction from Etsy. |
Etsy Help recommends the Seller App path for a seller’s own listings and inventory. Commercial Access is not automatic: Etsy reviews requests and expects compliance with its terms and caching policies. Do not present cached listing information as current when your application has not refreshed it.
3. Authentication and request shape
- Register an Etsy application and obtain its API keystring and shared secret.
- Store credentials in server-side environment variables or a secret manager.
- Send an HTTPS request to the appropriate v3 endpoint with
x-api-key: keystring:shared_secret. - For private or write endpoints, complete OAuth 2.0 and send
Authorization: Bearer user_id.oauth_token. - Request only the scopes needed, such as listing-read or listing-write.
Never put an API key, shared secret, or OAuth token in browser JavaScript, a mobile binary, a public repository, or a client-side URL. Treat a leaked token as compromised and rotate it.

Public application request with cURL
export ETSY_API_KEYSTRING='YOUR_KEYSTRING'
export ETSY_SHARED_SECRET='YOUR_SHARED_SECRET'
export ETSY_SHOP_ID='YOUR_SHOP_ID'
curl --fail-with-body --silent --show-error \\
-H "x-api-key: ${ETSY_API_KEYSTRING}:${ETSY_SHARED_SECRET}" \\
"https://api.etsy.com/v3/application/shops/${ETSY_SHOP_ID}/listings/active?limit=25&offset=0"
The active-listings response is paginated. Keep the raw response long enough to audit your import, then normalize only the fields your use case needs.
OAuth request for authorized private data
curl --fail-with-body --silent --show-error \\
-H "x-api-key: ${ETSY_API_KEYSTRING}:${ETSY_SHARED_SECRET}" \\
-H "Authorization: Bearer ${ETSY_USER_ID}.${ETSY_OAUTH_TOKEN}" \\
"https://api.etsy.com/v3/application/shops/${ETSY_SHOP_ID}/listings/active?limit=25&offset=0"
The exact OAuth scopes and endpoint authorization requirements come from the API reference for the operation you call. Ask for the smallest scope that satisfies the feature.
4. Python: collect listings with pagination
import os
import time
import requests
API_KEYSTRING = os.environ['ETSY_API_KEYSTRING']
SHARED_SECRET = os.environ['ETSY_SHARED_SECRET']
SHOP_ID = os.environ['ETSY_SHOP_ID']
headers = {
'x-api-key': f'{API_KEYSTRING}:{SHARED_SECRET}',
'Accept': 'application/json',
}
rows = []
offset = 0
limit = 100
while True:
response = requests.get(
f'https://api.etsy.com/v3/application/shops/{SHOP_ID}/listings/active',
headers=headers,
params={'limit': limit, 'offset': offset},
timeout=30,
)
response.raise_for_status()
payload = response.json()
batch = payload.get('results', [])
rows.extend(batch)
if len(batch) < limit:
break
offset += limit
time.sleep(0.2)
for listing in rows:
print({
'listing_id': listing.get('listing_id'),
'shop_id': listing.get('shop_id'),
'title': listing.get('title'),
'url': listing.get('url'),
'price': listing.get('price'),
'quantity': listing.get('quantity'),
'updated': listing.get('updated_timestamp'),
})
For a private endpoint, add the bearer token to headers. In production, replace the fixed sleep with your measured rate-limit strategy and persist the last successful offset or cursor checkpoint.
5. Node.js: fetch listings safely
const keystring = process.env.ETSY_API_KEYSTRING;
const sharedSecret = process.env.ETSY_SHARED_SECRET;
const shopId = process.env.ETSY_SHOP_ID;
async function getListings() {
const all = [];
const limit = 100;
for (let offset = 0; ; offset += limit) {
const url = new URL(`https://api.etsy.com/v3/application/shops/${shopId}/listings/active`);
url.searchParams.set('limit', String(limit));
url.searchParams.set('offset', String(offset));
const res = await fetch(url, {
headers: {
'x-api-key': `${keystring}:${sharedSecret}`,
'accept': 'application/json'
}
});
if (!res.ok) throw new Error(`Etsy API ${res.status}: ${await res.text()}`);
const page = await res.json();
all.push(...(page.results || []));
if (!page.results || page.results.length < limit) break;
}
return all;
}
getListings().then(listings => console.log(JSON.stringify(listings, null, 2)));
6. Which listing and shop fields to store
The reference documents fields including listing_id, shop_id, title, description, state, creation and update timestamps, quantity, URL, tags, materials, listing type, processing windows, maker and era fields, and tax or shipping-related identifiers. Keep the source timestamps so downstream users can tell when a value was observed.
- Identity: listing ID, shop ID, URL.
- Merchandising: title, description, tags, materials, listing type.
- Availability: state, quantity, processing windows.
- Catalog history: creation and update timestamps.
- Commercial context: documented tax and shipping identifiers, where your access permits them.
Normalize text as Unicode, preserve the original title and description, and avoid silently changing seller content. If you build search indexes, record the indexing time separately from Etsy’s update time.
7. Prices, variations, and inventory
The listing price is the minimum possible price. It is not necessarily the amount a buyer pays for every variation. If a listing has size, color, personalization, or other offerings, call the listing-inventory method to obtain exact offering prices for available variations. Sold-listing data is private.
A safe price model stores the currency, the API value, the observation timestamp, and—when applicable—the selected offering or variation IDs. Do not label the minimum listing price as “starting price” unless your interface makes that meaning clear, and do not infer a variation’s price by parsing the public page.
8. Search, freshness, and caching
Design imports around the API’s documented pagination and filtering parameters. Fetch only the fields and records needed for the job, use bounded timeouts, and checkpoint progress. For recurring synchronization:
- Run an initial full import for the authorized shop or scope.
- Store Etsy’s update timestamps and your last successful synchronization time.
- Refresh changed records on a schedule appropriate to your product.
- Delete or mark unavailable records when the API reports their new state.
- Honor Etsy’s caching policies, especially for Commercial Access.
Cache responses to reduce duplicate calls, but display the retrieval time and define a freshness window. A cache hit is not proof that a listing is still available.
9. Why browser scraping and HTML parsing fail
Browser automation is fragile around consent dialogs, sign-in walls, bot checks, changing markup, lazy-loaded content, and regional responses. More fundamentally, Etsy’s developer documentation says: “Applications must not sidestep the API to retrieve or post Etsy data. Screen-scraping is not allowed.” Etsy’s API Terms of Use also restrict automated systems and browser extensions from accessing, analysing, or scraping Etsy sites, the API, or Etsy data unless Etsy expressly authorizes it in writing. They also restrict collecting Etsy content for analytics, machine learning, AI training, licensing, or content removal without express authorization.
If your project needs data Etsy does not expose for your authorized tier, request the appropriate access or ask Etsy for written authorization. Do not treat a public URL as permission to automate collection.
10. Troubleshooting common errors
| Symptom | Likely cause | Fix |
|---|---|---|
| 401 or 403 | Malformed x-api-key, missing OAuth, expired token, or insufficient scope. |
Check the exact keystring/shared-secret format, refresh OAuth, and request the scope documented for the operation. |
| Empty results | Wrong shop ID, filters that exclude records, or no active listings. | Verify the shop ID and test a minimal request with a small limit. |
| Price appears too low | You stored the listing’s minimum possible price. | Retrieve inventory offerings and store the selected variation price. |
| Duplicate listings | Retries appended a page twice or offsets were not checkpointed. | Upsert by listing_id and record page checkpoints. |
| 429 or throttling | Too many concurrent or repeated requests. | Reduce concurrency, add exponential backoff with jitter, and cache unchanged records. |
| Stale catalog | Cache policy or synchronization interval is too long. | Shorten the refresh window, show observed timestamps, and follow Etsy’s caching rules. |
| Token exposed in logs | Authorization headers or URLs were logged. | Redact secrets, rotate compromised credentials, and keep request logging structured. |
11. Reliability, performance, and cost planning
- Reliability: set connect and read timeouts, retry only transient failures, and make writes idempotent where the endpoint supports them.
- Performance: paginate with the largest permitted page size, process pages incrementally, and avoid fetching inventory for listings that do not have variations.
- Consistency: retain raw responses or a reproducible normalized record so a later correction can be audited.
- Cost: Etsy access and any commercial approval requirements are separate from your hosting, database, and queue costs. Do not assume an API response represents a sale or a guaranteed price.
- Compliance: document your access tier, requested scopes, retention period, and cache behavior before launch.
12. Or skip the browser setup
If you need a screenshot of a page you are authorized to capture—for documentation, QA, or an internal catalog—ScreenshotNeo provides a single HTTPS request instead of maintaining Playwright or Selenium infrastructure. Its API and examples are in the ScreenshotNeo docs.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
Cookie banners, newsletter popups, and chat widgets are removed before the shot; bot checks, blank pages, failed loads, timeouts, and cache hits are never billed, with the result identified by X-Page-Verdict and X-Billed headers. An MCP server lets Claude, Cursor, and other MCP clients use take_screenshot, get_page_info, and capture_pdf. You get 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
13. FAQ
Can I scrape Etsy search-result pages?
Not as a workaround for API access. Use the documented API and an access tier that covers your use case, or obtain written authorization from Etsy.
Is the listing price exact?
No. The documented listing price is the minimum possible price. Use listing inventory for exact available offerings and variations.
Can a Seller App read another seller’s shop?
The Seller App path is intended for the developer’s own shop. Use the Personal App or Commercial Access route when your application needs broader coverage.
Should I store every field?
Store identifiers, timestamps, fields needed by your product, and enough raw context to audit transformations. Minimize retention for data you do not use.
What should I do when the API lacks a field?
Check the reference and your access tier, then contact Etsy about an authorized solution. Do not fill the gap with browser automation.


