# Etsy Listing Search API Documentation

Scrappa's `GET /api/etsy/search` returns Etsy listings for a search query as structured JSON.

## What you get

Each listing has `listing_id`, `title`, `url`, `image`, `image_large`, `price`, `original_price`, `discount_percent`, `currency`, `rating`, `review_count`, `shop_id`, `shop_name`, `shop_url` and the flags `bestseller`, `popular_now`, `etsys_pick`, `star_seller`, `free_shipping` and `from_price`. `pagination.total_results` is the number of matches Etsy reports.

## Ads are removed

Etsy mixes paid ads into the results. They are removed from `data`, and `pagination.sponsored_removed` tells you how many. `position` counts the remaining listings of the page. A page can hold fewer listings than Etsy shows.

## Filters are honoured

`min_price`, `max_price`, `free_shipping` and `on_sale` are checked on every listing. A listing that breaks a filter is removed, and `pagination.filtered_out` counts them. Etsy reports the `sort` and `ship_to` it applied. If one is missing, the request returns `422` (`upstream_rejected`) instead of unfiltered listings.

## Currency

`currency` is the currency Etsy shows on the page. Prices are not converted.

## Rounded review counts

Search cards show review counts like `12.5k`. Then `review_count` is rounded and `review_count_is_rounded` is `true`. The product endpoint returns the exact count.

## Pagination

`page` is 1-20, because Etsy serves 20 result pages at most. The label always equals the page Etsy served. If Etsy served another page, the request fails with `503` and costs nothing. `has_more` tells you whether a next page exists.

## 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_search](https://scrappa.co/docs/etsy-api/etsy_search)
- **API group:** Etsy API
- **Endpoint:** `GET https://scrappa.co/api/etsy/search`

## 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 |
| --- | --- | --- | --- |
| `query` | string | Yes | Search words, for example leather wallet. |
| `page` | integer | No | Result page, 1-20. |
| `sort` | string | No | relevance (default), newest, price_low_to_high, price_high_to_low or top_customer_reviews. |
| `min_price` | number | No | Lowest listing price in the currency of the page. Cheaper listings are removed. |
| `max_price` | number | No | Highest listing price in the currency of the page. Dearer listings are removed. |
| `ship_to` | string | No | Two-letter country code such as DE or GB. Only listings that ship to that country. |
| `free_shipping` | boolean | No | true for listings with free shipping only. |
| `on_sale` | boolean | No | true for listings on sale only. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/etsy/search?query=leather+wallet&max_price=50&free_shipping=true"
```

## Example response

```json
{
    "success": true,
    "data": [
        {
            "position": 1,
            "listing_id": "1241528786",
            "title": "Personalized Leather RFID Wallet, Engraved Genuine Leather Custom Wallet",
            "url": "https://www.etsy.com/listing/1241528786/personalized-leather-rfid-wallet",
            "image": "https://i.etsystatic.com/35016605/r/il/a5f633/4007318605/il_255x319.4007318605_mj36.jpg",
            "image_large": "https://i.etsystatic.com/35016605/r/il/a5f633/4007318605/il_794xN.4007318605_mj36.jpg",
            "price": 28,
            "original_price": 70,
            "discount_percent": 60,
            "currency": "USD",
            "from_price": false,
            "rating": 4.9,
            "review_count": 12500,
            "review_count_is_rounded": true,
            "shop_id": "35016605",
            "shop_name": "PremiumEngrave",
            "shop_url": "https://www.etsy.com/shop/PremiumEngrave",
            "bestseller": true,
            "popular_now": true,
            "etsys_pick": false,
            "star_seller": true,
            "free_shipping": true
        }
    ],
    "pagination": {
        "page": 1,
        "has_more": true,
        "total_results": 89578,
        "filtered_out": 0,
        "sponsored_removed": 12
    },
    "applied_filters": {
        "query": "leather wallet",
        "max_price": 50,
        "free_shipping": true
    },
    "currency": "USD",
    "meta": {
        "endpoint_family": "etsy-search",
        "billable": true,
        "attempts": 1,
        "credits_charged": 10
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Filter Not Applied | Etsy did not apply a requested filter such as `ship_to` or `sort` (`upstream_rejected`). The request is rejected instead of returning unfiltered listings. 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)