# Etsy — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Discover what shoppers are searching for on Etsy by accessing real-time trending keywords and popular search terms that can help you identify market demand and optimize your product listings. Get instant access to autocomplete suggestions and "Popular right now" trends to stay ahead of customer interests and improve your shop's visibility.

**Category:** Marketplaces | **Website:** [etsy.com/](https://etsy.com/) | **Docs:** [parse.bot/marketplace/9812261a-267f-4ae6-94ff-7bc177701c7e/etsy-com-api](https://parse.bot/marketplace/9812261a-267f-4ae6-94ff-7bc177701c7e/etsy-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/etsy/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Browse category

Browse Etsy listings by category path. Returns paginated product listings within the specified category, parsed from the HTML listing cards.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_path` | string | Yes | Hierarchical category path using forward slashes (e.g. 'clothing/womens-clothing/dresses', 'jewelry/necklaces', 'jewelry/rings'). |
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/etsy/browse-category \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_path":"<string>","page":"<integer>"}'
```

### Get listing details

Retrieve full details for a single Etsy listing by its listing ID via Etsy's public JSON API. Returns product name, description, images, pricing, seller info, badges, tags, materials, and availability.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `listing_id` | string | Yes | Etsy listing ID (numeric string, e.g. '1548871956'). Obtainable from browse_category results[*].listing_id. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/etsy/get-listing-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"<string>"}'
```

### Get listing reviews

Retrieve reviews for a specific Etsy listing via the shop reviews API. Returns all recent shop reviews and filters for listing-specific ones. Providing the shop_id avoids an extra API call to resolve it.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `listing_id` | string | Yes | Etsy listing ID (numeric string). Obtainable from browse_category results[*].listing_id. |
| `shop_id` | string | No | Numeric shop ID. If omitted, auto-detected from the listing API. Obtainable from get_listing_details.shop_id. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/etsy/get-listing-reviews \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"<string>","shop_id":"<string>"}'
```

### Get shop info

Retrieve basic profile information for an Etsy shop by its shop name. Returns name, URL, logo, aggregate rating, review count, and shop ID.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `shop_name` | string | Yes | Etsy shop name as it appears in the shop URL (e.g. 'TheBeadChest'). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/etsy/get-shop-info \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"shop_name":"<string>"}'
```

### Get shop listings

List products from a specific Etsy shop with pagination. Returns basic product info including name, URL, image, price, and currency.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |
| `shop_name` | string | Yes | Etsy shop name as it appears in the shop URL (e.g. 'TheBeadChest'). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/etsy/get-shop-listings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","shop_name":"<string>"}'
```

### Search listings

Search for product listings on Etsy by keyword. Returns paginated results with basic product information extracted from structured data. Supports optional price range and attribute filters.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `is_handmade` | string | No | Filter handmade items. Accepted values: true, false. |
| `is_vintage` | string | No | Filter vintage items. Accepted values: true, false. |
| `max_price` | string | No | Maximum price filter value. |
| `min_price` | string | No | Minimum price filter value. |
| `page` | integer | No | Page number for pagination. |
| `query` | string | Yes | Search keyword (e.g. 'leather wallet'). |
| `sort_on` | string | No | Sort order. Accepted values: most_relevant, lowest_price, highest_price, date_desc. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/etsy/search-listings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"is_handmade":"<string>","is_vintage":"<string>","max_price":"<string>","min_price":"<string>","page":"<integer>","query":"<string>","sort_on":"<string>"}'
```

### Search shops

Search for Etsy shops by keyword. Returns a list of matching shop names and URLs extracted from the search results page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword for shops (e.g. 'jewelry', 'vintage clothing'). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/etsy/search-shops \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.