Fetch the current public detail of one Etsy listing from its direct product URL for listing research and competitor-page audits.
Core Concepts
- Direct listing URL required: use an Etsy HTTPS URL whose path is
/listing/<numeric-id>or/listing/<numeric-id>/<one-slug-segment>, with an optional trailing slash and query string. - One listing per call: this is a detail lookup, not Etsy keyword search or bulk screening.
- Structured public-page data: the response groups listing, price, media, shop, delivery, and review-summary fields.
- Current snapshot: values reflect what the public listing exposes when queried and may be absent or inconsistent.
Data Fields
| Field | Description |
|---|---|
| productId / productUrl | Etsy listing ID and canonical/product URL |
| title / description | Listing title and description sections |
| image / images | Primary image and full image list |
| price / lowPrice / highPrice / oldPrice | Current, range, and previous price strings when available |
| currency | Returned currency code |
| maxQuantity / variants | Reported maximum quantity and variation options |
| category | Etsy category breadcrumb |
| countryShippingFrom | Shipping origin country |
| deliveryDaysMin / deliveryDaysMax | Estimated delivery window; may be null or omitted |
| shopId / shopName / shopUrl / shopSales | Shop identity and public sales data |
| reviews / star / shopReviews | Listing review count, rating, and shop review count |
| highlightsTags / reviewsTags | Buyer-feedback highlights and tag frequencies |
| reviewsScores | Dynamic review-score breakdown; keys vary by listing |
| yearsOnEtsy | Public shop tenure |
| hasRatingsBadge / hasConvosBadge / hasShippingBadge | Public shop/listing badge flags |
| moreLikeUrl / searchPosition | Related-link or source-position fields when available |
The tool returns aggregate review signals, not individual review records.
Parameter Guide
| Parameter | Required | Default | Description |
|---|---|---|---|
| productUrl | Yes | - | Public HTTPS Etsy listing URL on etsy.com or a subdomain, without embedded credentials, using the default HTTPS port; the path is /listing/<numeric-id> with at most one slug segment, and an optional trailing slash/query string |
Search pages, shop pages, non-Etsy hosts, and listing URLs without a numeric listing ID are not valid inputs.
How to Call
- API Endpoint：
POST /etsy/product/detail(For complete parameters/response/error codes, seereferences/api.md） - Python Script：
python scripts/etsy_product_detail.py '<JSON 参数>' [--inline] - Cost Constraints: This tool consumes computing power; by default, the same parameter combination in the same session is called only once, and the script has a 24h local cache. On failure/empty results, do not automatically switch keywords, paginate, or change the zip code to probe repeatedly; if continued retrieval is needed, first explain to the user that additional consumption will be incurred.
Output Strategy (Script Default Behavior)：
- Alwayswrite the complete response to
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-etsy-product-detail-<timestamp>.json（<cwd>is the working directory when the script is executed, which in Claude Code is the current project directory;<session>is taken from the environment variableSESSION_ID, automatically aggregated according to the user task;writing to /tmp is prohibited, and an error is reported if the current directory is not writable) - Response body ≤ 8 KB: after writing to disk, print the complete JSON to stdout
- Response body > 8 KB: after writing to disk, stdout outputs only a summary (top-level fields, common counts such as
total/costToken, the length of the largest list field + the first 3 samples) - Add
--inlineto force full printing to stdout (also written to disk)
Data Reading Suggestions: First look at the summary to determine whether it is sufficient; when specific fields are needed, prefer to use jqorConvertFrom-Json to extract on demand from the saved json file, avoiding bringing the entire JSON into context.
Resolve Authentication and Computing Power Issues
When the following abnormal situations occur, use references/onboarding.md to guide problem resolution:
Abnormal Situation
- API Key Not Configured: The environment variable is not configured
LINKFOX_AGENT_API_KEY, andLINKFOXAGENT_API_KEY。 - is also not configured. Response 401 or 402 status code。
- The response indicates insufficient computing power or balance: The message contains “insufficient computing power balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge” or similar meanings.
Usage Examples
python scripts/etsy_product_detail.py '{"productUrl":"https://www.etsy.com/listing/1710567856/its-okay-to-make-some-mistakes-shirt"}'
Display Rules
- Lead with title, listing ID, shop name, category, price range, and currency.
- Show the primary image inline and offer the remaining image count rather than rendering every image by default.
- Present variants and quantity only when returned; an empty variants list is a valid result.
- Keep listing reviews and shop reviews distinct, and label buyer-feedback tags as aggregate signals.
- Show delivery estimates only when both source values are meaningful; preserve nulls as unavailable.
- Do not normalize or convert price strings without an explicit user request.
- Treat missing, empty, or implausible shop fields as extraction uncertainty; do not silently repair them.
- For long descriptions and image arrays, summarize first and extract exact content from the saved JSON on demand.
Important Limitations
- Public Etsy page structure changes can cause fields to be absent, empty, or occasionally misidentified.
star, price fields, delivery estimates, shop metadata, and badges are not guaranteed for every listing.- The response includes review counts, tags, and aggregate scores, but not individual buyer reviews.
- This tool does not provide historical prices, Etsy keyword rankings, or guaranteed sales estimates.
- This tool does not search Etsy; use the Etsy product-query skill when the user needs keyword or multi-filter discovery.
User Expression & Scenario Quick Reference
Applicable — one known Etsy listing URL:
| User Says | Scenario |
|---|---|
| “Check the details of this Etsy product link” | Listing detail lookup |
| “Extract the title, description, and images of this Etsy Listing” | Listing-content extraction |
| “Look at its price range, variations, and shipping information” | Offer and delivery audit |
| “What is the shop and review overview of this Etsy product?” | Shop and review-summary lookup |
Not applicable:
- Etsy keyword search, category discovery, or multi-product screening
- Etsy shop search/ranking without a specific listing URL
- Individual review retrieval or sentiment analysis from full review text
- Listing creation, editing, order management, or other seller-account operations
Computing Power Consumption Rules
Consumes 6 computing power.
Users pay fees due to computing power consumption. Repeated queries for other Listings are billed separately; before continuing to call, the user should be informed of the additional consumption.
Feedback:
Auto-detect and report feedback via the Feedback API when the described capability differs from actual behavior, results miss the user's intent, the user expresses praise or dissatisfaction, or the skill can be improved. Follow references/api.md without interrupting the user's flow.
For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.