Use Etsy Open API v3 rather than scraping Etsy’s web pages. The API is the supported way to retrieve listing and shop data, and Etsy explicitly says applications must not sidestep the API: “Screen-scraping is not allowed.” Every request uses HTTPS and an x-api-key; private-data and write operations also require OAuth 2.0. This guide shows how to collect listing records, shop names, prices, and variation data while keeping credentials, caching, and permissions compliant.
What “scraping Etsy listings” should mean
For a production integration, “scraping” should mean making authorized API requests and storing the fields your application is allowed to use. Copying Etsy’s public HTML, driving a browser, or installing an automated browser extension is not an acceptable workaround. Etsy’s developer documentation states that applications must not sidestep the API to retrieve or post Etsy data, and its API Terms of Use (updated June 16, 2025) also restrict automated systems from accessing, analyzing, or scraping Etsy sites, the API, or Etsy data unless Etsy has expressly authorized it in writing.
The API provides structured listing and shop records instead of fragile page markup. Your access level determines whether the integration can read one shop, work across multiple shops, or operate as a reviewed commercial application.
Choose the Etsy access tier that fits your project
| Access tier | Best fit | What to expect |
|---|---|---|
| Seller App | Your own shop | Etsy Help recommends this path for a seller’s own listings, orders, inventory, and related data. |
| Personal App | A developer building beyond one shop at limited scale | Use it for a non-commercial or limited multi-shop integration that stays within Etsy’s requirements. |
| Commercial Access | A broader product serving other sellers | Requires an approved Personal App, a compliant home page, clear distinction from Etsy, adherence to caching policies, and manual review. Approval is not automatic. |
Do not request broader access simply because it is available. Ask for the smallest scope and shop coverage your application needs. Commercial applications must also follow Etsy’s caching rules; do not present old listing content as current.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match#1 Best Overall
What data the listings API gives you
Listing responses can include identifiers and merchandising fields such as:
listing_idandshop_idtitle,description, URL, tags, and materialsstate, creation and update timestamps, and quantity- listing type, processing windows, maker and era fields
- tax- and shipping-related identifiers
The documented price is the minimum possible price for the listing. It is not necessarily the amount a buyer will pay for every variation. If a listing has size, color, or other offerings, call the listing-inventory method and read the exact offering prices there. Sold-listing data is private, so do not assume a public listing request exposes historical sales.
Set up an authorized API request
- Register the appropriate Etsy application. Obtain the API keystring and shared secret. Keep both on your server or in a secret manager.
- Select the least-privileged access. Public application requests use the API key. Private-data and write endpoints require OAuth 2.0 and the scope required by that endpoint, such as a listing-read or listing-write scope.
- Use HTTPS v3 endpoints. Etsy API routes are under
https://api.etsy.com/v3/application/. - Send the key header on every request. Its value is the keystring, a colon, and the shared secret:
x-api-key: KEYSTRING:SHARED_SECRET. - Add OAuth only when required. The header format is
Authorization: Bearer USER_ID.OAUTH_TOKEN. Never put this token in browser JavaScript, a mobile app bundle, or a published code sample.
Retrieve active listings from one shop
The following examples request a shop’s active listings. Replace the placeholders with secrets held in your environment. The route shown is an Etsy v3 shop-listings route; check the current reference for the exact operation and fields your access level permits.
cURL
curl -G "https://api.etsy.com/v3/application/shops/SHOP_ID/listings/active"
-H "x-api-key: KEYSTRING:SHARED_SECRET"
-d limit=100
-d offset=0Python
import os
import requests
shop_id = os.environ["ETSY_SHOP_ID"]
keystring = os.environ["ETSY_KEYSTRING"]
shared_secret = os.environ["ETSY_SHARED_SECRET"]
url = f"https://api.etsy.com/v3/application/shops/{shop_id}/listings/active"
headers = {"x-api-key": f"{keystring}:{shared_secret}"}
params = {"limit": 100, "offset": 0}
response = requests.get(url, headers=headers, params=params, timeout=30)
response.raise_for_status()
payload = response.json()
for listing in payload.get("results", []):
print(listing.get("listing_id"), listing.get("title"), listing.get("price"))Node.js
const shopId = process.env.ETSY_SHOP_ID;
const keystring = process.env.ETSY_KEYSTRING;
const sharedSecret = process.env.ETSY_SHARED_SECRET;
const url = new URL(`https://api.etsy.com/v3/application/shops/${shopId}/listings/active`);
url.search = new URLSearchParams({ limit: '100', offset: '0' });
const res = await fetch(url, {
headers: { 'x-api-key': `${keystring}:${sharedSecret}` }
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const payload = await res.json();
for (const listing of payload.results ?? []) {
console.log(listing.listing_id, listing.title, listing.price);
}For additional pages, increase the offset (or follow the pagination values returned by the operation) until no results remain. Store the listing ID as your durable key; titles and descriptions can change, and timestamps let you identify updates.
Get exact prices for variations
Use the listing-inventory method for each listing when you need the price of a specific offering rather than the listing’s minimum. Match the returned offering to the variation combination selected by your application, then store the currency and amount together. Treat a price as a snapshot: inventory, quantity, and variation prices can change after your request.
Do not infer a sale price from the listing title, description, or rendered HTML. If your use case needs tax, shipping, or checkout totals, those are separate concerns from the listing’s documented minimum price and may require additional authorized data.
Collecting shop names and marketplace-wide data
One shop
A Seller App is the straightforward choice when the data belongs to the developer’s own shop. Keep the shop ID with each listing so records remain traceable even when titles are edited.
Multiple shops
A Personal App can support an application that works beyond one shop at limited scale. Each shop’s authorization and permitted scopes still apply; one shop’s token does not grant access to another shop’s private data.
Broader commercial products
Commercial Access is intended for applications serving other sellers. Etsy requires a compliant home page, a clear distinction from Etsy, caching-policy compliance, and manual review. Design your consent, deletion, refresh, and support flows before submitting; approval is not guaranteed.
Build a dependable collection pipeline
Normalize the response
Save the listing ID, shop ID, title, state, URL, quantity, minimum price, currency, created and updated timestamps, and the raw response version you are permitted to retain. Keep descriptions and tags in fields that can be replaced on refresh rather than appended repeatedly.
Rank #3
Refresh deliberately
Use update timestamps or your own synchronization cursor to request changed records. Follow Etsy’s caching policies for your access tier, document the retention period, and label cached values with the time they were fetched. Never imply that a cached listing is live inventory.
Protect credentials
- Store the keystring, shared secret, and OAuth tokens in environment variables or a secrets manager.
- Restrict logs so headers and authorization tokens cannot appear in error output.
- Use server-side calls and a narrow allowlist of API operations.
- Rotate credentials if they are exposed and invalidate affected OAuth grants.
Handle pagination and transient failures
Process pages incrementally and checkpoint the last successful page. Retry only temporary network or server failures with bounded exponential backoff. Do not blindly retry authorization errors, malformed requests, or policy denials; fix the request or permissions first.
Free tools Windows power users keep installed
One-click scans. No signup required.
Why browser scraping fails in practice
- Policy risk: Etsy prohibits screen-scraping and broadly restricts automated access without written authorization.
- Fragile selectors: HTML classes, consent dialogs, experiments, and lazy-loaded sections can change without notice.
- Incorrect prices: A page can show one selected variation while the API’s listing price is only the minimum possible price.
- Incomplete privacy boundary: Public page visibility does not make sold or private listing data public.
- Operational overhead: Browser sessions require cookie handling, rendering, retries, and bot-check handling that an authorized API client avoids.
Troubleshooting common API errors
401 or 403 response
Check that the x-api-key value is exactly keystring:shared_secret, that the key belongs to the intended application, and that an OAuth bearer token is present when the operation is private or writes data. Confirm the token has the required scope and has not expired or been revoked.
404 response
Verify the shop ID, listing ID, and operation path. A deleted, unavailable, or inaccessible shop can produce the same symptom as a malformed identifier, so test with a shop your application is authorized to access.
Results are empty
Check the listing state and pagination parameters. An empty active-listings page does not prove that a shop has never had listings; it may have no currently active items or your filter may exclude them.
Rank #4
Price does not match a variation
This is expected when you read the listing-level price. Retrieve inventory offerings and select the exact variation combination instead of treating the minimum as universal.
Recommended Free Tools
Data appears stale
Inspect your cache timestamp and refresh logic. Commercial applications must follow Etsy’s caching policies and must not present old content as current.
Request works locally but not in production
Compare environment variables, outbound HTTPS access, clock and token validity, and server-side versus client-side execution. A common cause is a secret omitted from the deployment or an OAuth token accidentally sent from a browser.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If you only need a visual record of an Etsy page—not structured listing data—ScreenshotNeo can capture a URL with one request. It is not a substitute for Etsy’s authorized API or permission to collect Etsy data, but it is useful for documenting a page or checking a rendered result. The service accepts the cookie or consent banner like a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets before capture, and lets you turn each cleanup step off.
See the ScreenshotNeo API documentation for all options. A basic call is:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://www.etsy.com -o shot.webpOnly clean shots are billed. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and each response identifies the result with X-Page-Verdict and X-Billed headers. ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
| Plan | Allowance | Price |
|---|---|---|
| Free | 1,000 shots/month | $0, no card |
| Starter | 3,000 shots | $5 |
| Growth | 15,000 shots | $15 |
| Pro | 60,000 shots | $39 |
| Scale | 250,000 shots | $99 |
| Business | 1,000,000 shots | $249 |
Yearly billing provides two months free, and every feature is available on every plan. Start with 1,000 free screenshots a month—no card required.
Frequently Asked Questions
Can I use Etsy data to train an AI model or build analytics without asking Etsy?
No. Etsy’s terms restrict collecting Etsy content for analytics, machine learning, or AI training unless Etsy has expressly authorized that use in writing.
Is Commercial Access granted immediately after I submit an application?
No. Etsy describes Commercial Access as a manually reviewed program with additional home-page, distinction, and caching requirements.
Should an API key ever appear in frontend code?
No. Keep the keystring, shared secret, and OAuth tokens on a server or in a secrets manager; frontend code can expose them to anyone who loads the page.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
