datawebotEtsy listing data: variations, personalization and access terms
Etsy listing IDs, provenance, variation and personalization fields explained alongside current terms for automated access and API use.
Check Etsy’s automated-access terms first
Etsy’s Terms of Use, last updated September 30, 2026, say in §6(C) that users agree not to crawl, scrape or spider any Services page without Etsy’s express permission, and direct API users to the API Terms. Etsy’s API Terms of Use, last updated August 18, 2026, separately restrict automated systems and browser extensions that access, analyze or scrape the Etsy Site, API or Etsy data unless Etsy expressly authorizes them in writing. Sections 5(24)–(25) also restrict API collection, scanning or requests for analytics, machine learning, AI training, licensing or content removal without Etsy’s express written authorization. An API key, OAuth consent or app access tier alone does not provide that purpose authorization. This page summarizes Etsy’s published terms and documentation; it is not a legal conclusion.
Scroll to compare →
| Published boundary | Etsy documentation says | Scope for this page |
|---|---|---|
| Terms of Use §6(C) · September 30, 2026 | Crawling, scraping or spidering any Services page requires Etsy’s express permission. | Listing fields below describe distinctions in authorized data; no collection path is provided. |
| API Terms §5(24) · August 18, 2026 | Automated systems or browser extensions may not access, analyze or scrape Etsy Site, API or Etsy data unless expressly authorized in writing by Etsy. | API access tiers and credentials are not presented as blanket permission for automated analysis. |
| API Terms §5(25) · August 18, 2026 | Using the API to collect, scan or request Etsy content for analytics, machine learning, AI training, licensing or content removal requires Etsy’s express written authorization. | Do not treat public listing endpoints as implied permission for competitor-price analytics. |
Keep each listing tied to its shop, chosen option and provenance
Etsy’s current Seller Policy asks sellers to represent how an item was made, by whom, and where it ships from, and to disclose production partners and AI-created items where applicable. Treat these as seller-stated details, not verified facts or guaranteed API fields. For authorized seller data, preserve each listing, shop and selected option together.
Scroll to compare →
| Record layer | Fields to preserve | How to interpret |
|---|---|---|
| Listing identity | listing_id; original listing URL; title; category; item/listing form when stated, such as physical or digital. | Use listing and shop IDs together; a shared title does not establish the same underlying item. |
| Shop identity | shop_id; shop name when present. | Keep the seller associated with the listing. |
| Seller-described item context | How it was made and by whom; where it ships from; stated origin, components or materials; disclosed production partner; AI-created disclosure where shown. | Retain the seller’s wording and attribution. Do not infer missing facts or assume every statement is an API field. |
| Selected option | Every variation property name/value tuple and SKU only where exposed. | Keep the complete option tuple with the selected version. |
| Price and market context | Displayed price and currency for the selected version; destination or shipping context when visible; region and observation time for an authorized human-reviewed reference. | A variation price is the total price for that version, not an added delta. Keep market and time context attached to the observation. |
Separate preset variations from personalization prompts
Etsy distinguishes preset variations that affect a version’s price, inventory or SKU from Custom options that collect details for a personalized order. Keep reusable listing definitions separate from buyer-specific answers and custom requests.
Scroll to compare →
| Listing input | Current Etsy description | Record boundary |
|---|---|---|
| Variation | Etsy allows up to three item attributes. The price set for each option is the total price for that version, not an additional cost. | Preserve the complete property/value tuple and the selected full-price meaning. |
| Custom variation and search | Seller-created variation names do not filter Etsy search results; available standard attributes depend on the listing category. | Keep custom labels distinct from Etsy’s category attributes; do not imply they are search facets. |
| Digital listing | Etsy’s help says listing variations are not supported for digital items. | Do not assume a digital listing has physical-item variation inventory. |
| Personalization definition | A listing can define up to five Custom options fields: text box, list of options or file upload. Add-on pricing is supported for optional text fields and appears in the updated total. | Keep prompt type, required status, instructions and any stated add-on price with the listing definition. |
| Buyer answer or custom order | A prompt definition differs from a buyer’s response. Etsy describes a custom listing as buyer-specific and created from the original Custom Request Message. | Do not publish buyer answers or custom-request text as public catalog data; keep order-level details separate. |
Read API fields with their scope and purpose limits
Etsy’s Open API documentation explains credentials, app review and data fields. Those platform mechanisms describe access scope; they do not replace the separate written-purpose authorization required by Etsy’s current API Terms for the restricted automated analysis and analytics uses above.
Scroll to compare →
| API concept | Etsy documentation describes | Boundary to preserve |
|---|---|---|
| Authentication | Every Open API v3 request requires an x-api-key. OAuth is additionally required on scoped endpoints for private data or write operations. | An API key or scoped OAuth access does not itself authorize analytics or another purpose restricted by API Terms §§5(24)–(25). |
| App access tiers | The current guide describes Seller Apps for a developer’s own registered shop; Personal Apps for uses beyond that shop at limited scale, subject to Etsy review and limits; and Commercial Access as a manually reviewed upgrade from an approved Personal App for broader-scale apps other sellers connect to, with OAuth consent and token scopes governing seller-specific access. | These tiers do not override API Terms §§5(24)–(25), authorize scraping, or grant the purpose-specific written authorization described there. |
| Listing inventory | getListingInventory requires listings_r. Some listings have no inventory record if they were not created or edited with Etsy inventory tools; SKU data is returned only when the requester owns the inventory record. | Public listing visibility does not establish inventory ownership or guarantee an inventory record. |
| Distinct data objects | Public listing descriptions, inventory records, personalization question definitions and order-level answers represent different data scopes. | Keep prompt definitions separate from private answers and transaction data. |
Content reviewed 2026-10-07.