# Etsy Shop Reviews API Documentation

Scrappa's `GET /api/etsy/reviews` returns the customer reviews of one Etsy shop as structured JSON.

## Input

`shop` is the shop name as in the shop link. Reviews of a single listing are not part of this API yet: `listing_id` is rejected with `422`.

## What you get

`data` has `shop`, `rating`, `review_count` and `reviews`. Each review has `review_id`, `rating`, `text`, `author`, `author_url`, `date`, `listing_id`, `listing_title`, `listing_url`, `listing_image` and `author_image`. One page holds about 14 reviews, newest first.

## Pagination

`page` is 1-100 and the label always equals the page Etsy served. `pagination.has_more` tells you whether a next page exists. A page after the last page answers `503` 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_reviews](https://scrappa.co/docs/etsy-api/etsy_reviews)
- **API group:** Etsy API
- **Endpoint:** `GET https://scrappa.co/api/etsy/reviews`

## 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 |
| --- | --- | --- | --- |
| `shop` | string | Yes | Shop name as in the shop link. |
| `page` | integer | No | Review page, 1-100. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/etsy/reviews?shop=PremiumEngrave&page=1"
```

## Example response

```json
{
    "success": true,
    "data": {
        "shop": "PremiumEngrave",
        "rating": 4.9,
        "review_count": 12467,
        "reviews": [
            {
                "review_id": "5269906339",
                "rating": 5,
                "text": "Very nice quality leather.",
                "author": "Debora",
                "author_url": "https://www.etsy.com/people/example",
                "date": "2026-11-03",
                "listing_id": "1241528786",
                "listing_title": "Personalized Leather RFID Wallet",
                "listing_url": "https://www.etsy.com/listing/1241528786/personalized-leather-rfid-wallet",
                "listing_image": "https://i.etsystatic.com/4007318605/r/il/a5f633/4007318605/il_170x135.4007318605_mj36.jpg",
                "author_image": "https://i.etsystatic.com/site-assets/images/avatars/default_avatar.png?width=75"
            }
        ]
    },
    "pagination": {
        "page": 1,
        "has_more": true
    },
    "meta": {
        "endpoint_family": "etsy-reviews",
        "billable": true,
        "attempts": 1,
        "credits_charged": 10
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 404 | Not Found | Etsy has no shop 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)