# Etsy Listing Details API Documentation

Scrappa's `GET /api/etsy/product` returns the full record of one Etsy listing as structured JSON.

## Input

Pass `listing_id` (the 6 to 12 digit number in the listing link) or `url` (an etsy.com listing link). Any other host is rejected with `422`.

## What you get

`data` has `listing_id`, `url`, `title`, `description`, `category` (top level first), `price` (`current`, `max`, `original`, `original_max`, `discount_percent`, `currency`), `availability`, `quantity_available`, `rating` (`value`, `count`), `images` (full size and thumbnail), `materials`, `highlights`, `variations`, `shipping`, `shop`, `favorites_count`, `listed_on`, `sample_reviews` and `faqs`.

## Variations

`variations` lists each choice (for example Color, Size) with its options. Each option has `id`, `label` and `price` when the option changes the price. `price.max` is the highest price across the options.

## Shipping

`shipping` has `cost`, `free_shipping`, `ships_from`, `origin_country`, `destination_country`, `estimated_delivery` and `returns`. The destination and delivery date are the ones Etsy shows for a buyer in the United States.

## Removed listings

A removed or unknown listing answers `404` (`not_found`) and costs nothing.

## Credits

A successful request costs **10 credits**. Etsy needs a full browser for every page, so it costs more than a plain request. Errors, blocks and `404` answers cost nothing. The response shows the charge in `meta.credits_charged`.

- **Documentation:** [https://scrappa.co/docs/etsy-api/etsy_product](https://scrappa.co/docs/etsy-api/etsy_product)
- **API group:** Etsy API
- **Endpoint:** `GET https://scrappa.co/api/etsy/product`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `listing_id` | string | No | Numeric listing id, for example 1241528786. Use this or url. |
| `url` | string | No | Link of an Etsy listing. Use this or listing_id. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/etsy/product?listing_id=1241528786"
```

## Example response

```json
{
    "success": true,
    "data": {
        "listing_id": "1241528786",
        "url": "https://www.etsy.com/listing/1241528786/personalized-leather-rfid-wallet",
        "title": "Personalized Leather RFID Wallet, Engraved Genuine Leather Custom Wallet",
        "description": "This Personalized Leather RFID Wallet is the perfect gift for him.",
        "category": [
            "Bags & Purses",
            "Wallets & Money Clips",
            "Wallets"
        ],
        "price": {
            "current": 28,
            "max": 50,
            "original": 70,
            "original_max": 125,
            "discount_percent": 60,
            "currency": "USD"
        },
        "availability": "InStock",
        "quantity_available": 1520,
        "rating": {
            "value": 4.9,
            "count": 7952
        },
        "images": [
            {
                "url": "https://i.etsystatic.com/35016605/r/il/a5f633/4007318605/il_fullxfull.4007318605_mj36.jpg",
                "thumbnail": "https://i.etsystatic.com/35016605/r/il/a5f633/4007318605/il_340x270.4007318605_mj36.jpg"
            }
        ],
        "materials": [
            "Leather",
            "nylon"
        ],
        "highlights": [
            "Made by PremiumEngrave",
            "Gift wrapping available"
        ],
        "variations": [
            {
                "name": "Color",
                "options": [
                    {
                        "id": "2682504516",
                        "label": "Light Brown",
                        "price": null
                    }
                ]
            }
        ],
        "shipping": {
            "cost": 0,
            "currency": "USD",
            "free_shipping": true,
            "ships_from": "Rogers, MN",
            "origin_country": "US",
            "origin_region": "MN",
            "destination_country": "US",
            "estimated_delivery": "Nov 7-12",
            "returns": "Returns & exchanges not accepted"
        },
        "shop": {
            "id": "35016605",
            "name": "PremiumEngrave",
            "url": "https://www.etsy.com/shop/PremiumEngrave",
            "logo": "https://i.etsystatic.com/35016605/r/isla/14595d/77586647/isla_500x500.77586647_alxu1nyl.jpg"
        },
        "favorites_count": 19174,
        "listed_on": "2026-11-03",
        "sample_reviews": [
            {
                "rating": 5,
                "text": "Great wallet, exactly as described",
                "author": "Brittany",
                "date": "2026-11-03"
            }
        ],
        "faqs": [
            {
                "question": "Do you accept returns?",
                "answer": "Not for custom items."
            }
        ]
    },
    "meta": {
        "endpoint_family": "etsy-listing",
        "billable": true,
        "attempts": 1,
        "credits_charged": 10
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 404 | Not Found | Etsy has no listing with that name or id (`not_found`). A removed listing also answers 404. Non-billable. |
| 422 | Validation Error | A query parameter is missing, unknown or unusable. Unknown parameters are rejected, never ignored. Non-billable. |
| 503 | Upstream Unavailable | Etsy could not be reached in time or answered with a block or an unexpected page (`upstream_unavailable`, `upstream_blocked`, `parser_drift`). Retryable and never billed. Clients are never rate limited. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)