# Etsy API

> Etsy provides listing, item, and shop data as a workflow and API.

Etsy searches listings using required search words and optional price, destination, shipping, result count, and sort inputs. Get listing returns item details from a required link or name, with an optional shop name to narrow name searches. Get shop returns a public shop profile and current listings from a required shop name or link, with an optional listing count.

- Page: https://fous.com/workflows/etsy
- Handle: `@etsy`
- Category: [Commerce](https://fous.com/workflows/category/commerce)
- Source website: https://etsy.com
- Last verified: Sep 28, 2026
- Fous is not affiliated with Etsy.

## Methods

### Get listing

Operation `get_listing`, version 1. 1 credit per call.

Get the details of one public Etsy item from its link or name. Name searches choose the closest matching listing; details not shown publicly may be missing.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `shop` | string | no | `"HoiauCraft"` | Shop name to narrow an item-name search, for example HoiauCraft. |
| `listing` | string | yes | `"https://www.etsy.com/listing/1024603588/personalized-birth-flower-disc-necklace"` | Etsy item link or item name, for example Custom birth flower necklace. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "listing"
  ],
  "properties": {
    "shop": {
      "type": "string",
      "default": "",
      "description": "Shop name to narrow an item-name search, for example HoiauCraft.",
      "examples": [
        "HoiauCraft"
      ]
    },
    "listing": {
      "type": "string",
      "description": "Etsy item link or item name, for example Custom birth flower necklace.",
      "examples": [
        "https://www.etsy.com/listing/1024603588/personalized-birth-flower-disc-necklace",
        "Custom birth flower necklace",
        "vintage brass candlestick"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "listing": "https://www.etsy.com/listing/1024603588/personalized-birth-flower-disc-necklace"
    },
    {
      "shop": "HoiauCraft",
      "listing": "Custom birth flower necklace"
    },
    {
      "listing": "vintage brass candlestick"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `price` | number | `19.9` | Regular price, or current price when not on sale. |
| `title` | string | `"Personalized Birth Flower Disc Necklace, Initial Charm, Bridesmaid Gift"` | Item title. |
| `currency` | string | `"USD"` | Currency code for the item price. |
| `materials` | array |  | Materials listed for this item. |
| `shop_name` | string or null | `"HoiauCraft"` | Seller shop name. |
| `listing_id` | string | `"1024603588"` | Etsy listing ID. |
| `sale_price` | number or null | `14.92` | Current discounted price if the item is on sale. |
| `variations` | array |  | Selectable options for each item variation. |
| `variations[].name` | string | `"Finish and Disc Qty"` |  |
| `variations[].options` | array |  |  |
| `description` | string or null |  | Item description as plain text. |
| `photo_links` | array |  | Item photo links. |
| `item_reviews` | array |  | Up to 10 recent reviews of this item. |
| `item_reviews[].date` | string or null | `"2026-09-24"` |  |
| `item_reviews[].text` | string or null | `"Well made, love the designs, and the discs look great!"` |  |
| `item_reviews[].stars` | number or null | `5` |  |
| `listing_link` | string | `"https://www.etsy.com/listing/1024603588/personalized-birth-flower-disc-necklace"` | Etsy page for the item. |
| `shop_reviews` | integer or null | `23897` | Number of shop reviews. |
| `processing_time` | string or null | `"turn around time is about 1-3 business days"` | Seller processing time if stated. |
| `shipping_cost_us` | number or null | `0` | Shipping cost to the United States if shown. |
| `shop_star_rating` | number or null | `4.8` | Shop rating out of five stars. |
| `shipping_currency` | string or null | `"USD"` | Currency code for U.S. shipping cost if shown. |
| `estimated_delivery` | string or null | `"Order today to get by Oct 5-13"` | Estimated delivery as shown for the United States. |
| `handmade_or_vintage` | string or null | `"Handmade"` | Handmade or vintage label if shown on the item page. |

**Example input**

```json
{
  "listing": "https://www.etsy.com/listing/1024603588/personalized-birth-flower-disc-necklace"
}
```

**Example output**

```json
{
  "price": 19.9,
  "title": "Personalized Birth Flower Disc Necklace, Initial Charm, Bridesmaid Gift",
  "currency": "USD",
  "materials": [],
  "shop_name": "HoiauCraft",
  "listing_id": "1024603588",
  "sale_price": 14.92,
  "variations": [
    {
      "name": "Finish and Disc Qty",
      "options": [
        "SILVER-1 Disc ($17.17)",
        "SILVER-2 Discs ($19.42)",
        "SILVER-3 Discs ($21.67)"
      ]
    },
    {
      "name": "Necklace length",
      "options": [
        "16 Inches ($14.92 - $28.42)",
        "18 Inches ($17.17 - $28.42)",
        "20 Inches ($17.17 - $28.42)"
      ]
    }
  ],
  "description": "SHIPPING & DUTIES \nFor U.S. customers: You do not need to pay extra duties. We cover all customs duties on your behalf, so you won’t be charged additional fees upon delivery.\n\n♥ DETAILS ♥\n---Big disc(…",
  "photo_links": [
    "https://i.etsystatic.com/27106899/r/il/404836/3155517624/il_fullxfull.3155517624_joc1.jpg",
    "https://i.etsystatic.com/27106899/r/il/0267ed/3384396116/il_fullxfull.3384396116_c9rw.jpg",
    "https://i.etsystatic.com/27106899/r/il/b31624/3386281698/il_fullxfull.3386281698_ex8q.jpg"
  ],
  "item_reviews": [
    {
      "date": "2026-09-24",
      "text": "Well made, love the designs, and the discs look great!",
      "stars": 5
    },
    {
      "date": "2026-09-19",
      "text": "Really lovely piece, looks like the high end version. Thanks!",
      "stars": 5
    },
    {
      "date": "2026-09-13",
      "text": "Very cute and the perfect gift for my friend for her birthday",
      "stars": 5
    }
  ],
  "listing_link": "https://www.etsy.com/listing/1024603588/personalized-birth-flower-disc-necklace",
  "shop_reviews": 23897,
  "processing_time": "turn around time is about 1-3 business days",
  "shipping_cost_us": 0,
  "shop_star_rating": 4.8,
  "shipping_currency": "USD",
  "estimated_delivery": "Order today to get by Oct 5-13",
  "handmade_or_vintage": "Handmade"
}
```

### Get shop

Operation `get_shop`, version 1. 1 credit per call.

Get a public Etsy shop profile and its current listings in shop order. Shops on a break may have no current listings.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `shop` | string | yes | `"CaitlynMinimalist"` | Shop name or Etsy shop link, for example CaitlynMinimalist or https://www.etsy.com/shop/CaitlynMinimalist. |
| `max_listings` | integer | no | `20` | Maximum current listings to include, for example 20. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "shop"
  ],
  "properties": {
    "shop": {
      "type": "string",
      "minLength": 1,
      "description": "Shop name or Etsy shop link, for example CaitlynMinimalist or https://www.etsy.com/shop/CaitlynMinimalist.",
      "examples": [
        "CaitlynMinimalist",
        "https://www.etsy.com/shop/CaitlynMinimalist",
        "ModParty"
      ]
    },
    "max_listings": {
      "type": "integer",
      "default": 20,
      "maximum": 100,
      "minimum": 1,
      "description": "Maximum current listings to include, for example 20.",
      "x-fous-developer": true,
      "examples": [
        20,
        100
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "shop": "CaitlynMinimalist",
      "max_listings": 20
    },
    {
      "shop": "https://www.etsy.com/shop/CaitlynMinimalist",
      "max_listings": 100
    },
    {
      "shop": "ModParty"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `headline` | string or null | `"Bridesmaid Gifts, Wedding Favors & Decorations"` |  |
| `listings` | array |  |  |
| `listings[].price` | number or null |  |  |
| `listings[].title` | string |  |  |
| `listings[].photo_link` | string or null |  |  |
| `listings[].listing_link` | string |  |  |
| `listings[].currency_code` | string or null |  |  |
| `location` | string or null | `"Tustin, California"` |  |
| `shop_link` | string | `"https://www.etsy.com/shop/ModParty"` |  |
| `shop_name` | string | `"ModParty"` |  |
| `owner_name` | string or null | `"Hina Khan"` |  |
| `star_rating` | number or null | `4.9` |  |
| `star_seller` | boolean | `false` |  |
| `total_sales` | integer or null | `2077508` |  |
| `logo_image_link` | string or null | `"https://i.etsystatic.com/8617622/r/isla/8d0c06/72477773/isla_500x500.72477773_r6ch73hf.jpg"` |  |
| `announcement_text` | string or null |  |  |
| `number_of_reviews` | integer or null | `285135` |  |
| `year_opened_on_etsy` | integer or null | `2013` |  |

**Example input**

```json
{
  "shop": "ModParty"
}
```

**Example output**

```json
{
  "headline": "Bridesmaid Gifts, Wedding Favors & Decorations",
  "listings": [],
  "location": "Tustin, California",
  "shop_link": "https://www.etsy.com/shop/ModParty",
  "shop_name": "ModParty",
  "owner_name": "Hina Khan",
  "star_rating": 4.9,
  "star_seller": false,
  "total_sales": 2077508,
  "logo_image_link": "https://i.etsystatic.com/8617622/r/isla/8d0c06/72477773/isla_500x500.72477773_r6ch73hf.jpg",
  "announcement_text": "🎀 ModParty is Taking a Short Break 🎀 After 25 wonderful years of helping you celebrate life’s most special moments, we’re taking a pause to rest and reflect. 💌 If you’ve already placed an order, do…",
  "number_of_reviews": 285135,
  "year_opened_on_etsy": 2013
}
```

### Search listings

Operation `search_listings`, version 1. 1 credit per call.

Search Etsy items for sale and return USD prices, shop ratings, shipping, badges, ads, photos, and links in Etsy order. Review counts may be unavailable for some shops.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `sort` | string | no | `"lowest_price"` | Listing order, for example lowest_price. |
| `query` | string | yes | `"silver earrings"` | Words to search for, for example personalized necklace. |
| `ship_to` | string | no | `"GB"` | Destination country name or two-letter code, for example United Kingdom. |
| `max_price` | number | no | `50` | Highest item price in USD, for example 50; leave blank for no maximum. |
| `min_price` | number | no | `20` | Lowest item price in USD, for example 20; leave blank for no minimum. |
| `max_results` | integer | no | `25` | Maximum listings to return, for example 24. |
| `free_shipping_only` | boolean | no | `true` | Only show free-shipping items, for example true. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "sort": {
      "enum": [
        "relevance",
        "lowest_price",
        "highest_price",
        "top_customer_reviews",
        "most_recent"
      ],
      "type": "string",
      "default": "relevance",
      "description": "Listing order, for example lowest_price.",
      "examples": [
        "lowest_price",
        "most_recent"
      ]
    },
    "query": {
      "type": "string",
      "description": "Words to search for, for example personalized necklace.",
      "examples": [
        "silver earrings",
        "personalized necklace",
        "ceramic mug"
      ]
    },
    "ship_to": {
      "type": "string",
      "default": "United States",
      "description": "Destination country name or two-letter code, for example United Kingdom.",
      "examples": [
        "GB",
        "Canada"
      ]
    },
    "max_price": {
      "type": "number",
      "minimum": 0,
      "description": "Highest item price in USD, for example 50; leave blank for no maximum.",
      "examples": [
        50,
        65
      ]
    },
    "min_price": {
      "type": "number",
      "minimum": 0,
      "description": "Lowest item price in USD, for example 20; leave blank for no minimum.",
      "examples": [
        20,
        15
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 24,
      "maximum": 64,
      "minimum": 1,
      "description": "Maximum listings to return, for example 24.",
      "x-fous-developer": true,
      "examples": [
        25,
        12,
        14
      ]
    },
    "free_shipping_only": {
      "type": "boolean",
      "default": false,
      "description": "Only show free-shipping items, for example true.",
      "examples": [
        true
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "sort": "lowest_price",
      "query": "silver earrings",
      "ship_to": "GB",
      "max_price": 50,
      "min_price": 20,
      "max_results": 25,
      "free_shipping_only": true
    },
    {
      "query": "personalized necklace",
      "max_results": 12
    },
    {
      "sort": "most_recent",
      "query": "ceramic mug",
      "ship_to": "Canada",
      "max_price": 65,
      "min_price": 15,
      "max_results": 14
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `listings` | array |  | Listings in Etsy search order. |
| `listings[].price` | number | `13.84` | Current item price. |
| `listings[].title` | string | `"Custom Name Necklace, 18K Gold Plated Name Necklace, Personalized Name Necklace, Cursive Name Jewelry, Birthday Gift, C` | Listing title. |
| `listings[].shop_name` | string | `"AnyaShopStudio"` | Seller shop name. |
| `listings[].advertised` | boolean | `true` | Whether Etsy marks the item as an ad. |
| `listings[].bestseller` | boolean | `false` | Whether a Bestseller badge appears. |
| `listings[].listing_id` | string | `"1413455244"` | Etsy listing ID. |
| `listings[].photo_link` | string or null | `"https://i.etsystatic.com/34379934/r/il/628644/4796937795/il_794xN.4796937795_qnr6.jpg"` | Main listing photo link, or null. |
| `listings[].star_seller` | boolean | `true` | Whether a Star Seller badge appears. |
| `listings[].listing_link` | string | `"https://www.etsy.com/listing/1413455244/custom-name-necklace-18k-gold-plated"` | Listing page link. |
| `listings[].currency_code` | string | `"USD"` | Price currency code. |
| `listings[].free_shipping` | boolean | `true` | Whether the search card shows free shipping. |
| `listings[].original_price` | number or null | `27.69` | Price before the sale, or null. |
| `listings[].discount_percent` | number or null | `50` | Sale discount percentage, or null. |
| `listings[].shop_star_rating` | number or null | `4.9` | Shop rating out of five, or null. |
| `listings[].number_of_reviews` | integer or null | `59357` | Shop review count, or null. |

**Example input**

```json
{
  "query": "personalized necklace",
  "max_results": 12
}
```

**Example output**

```json
{
  "listings": [
    {
      "price": 13.84,
      "title": "Custom Name Necklace, 18K Gold Plated Name Necklace, Personalized Name Necklace, Cursive Name Jewelry, Birthday Gift, Christmas Gift for Her",
      "shop_name": "AnyaShopStudio",
      "advertised": true,
      "bestseller": false,
      "listing_id": "1413455244",
      "photo_link": "https://i.etsystatic.com/34379934/r/il/628644/4796937795/il_794xN.4796937795_qnr6.jpg",
      "star_seller": true,
      "listing_link": "https://www.etsy.com/listing/1413455244/custom-name-necklace-18k-gold-plated",
      "currency_code": "USD",
      "free_shipping": true,
      "original_price": 27.69,
      "discount_percent": 50,
      "shop_star_rating": 4.9,
      "number_of_reviews": 59357
    },
    {
      "price": 17.5,
      "title": "Custom Name Necklace for Women Personalized Engraved Bar Nameplate Necklace Dainty Gold Mothers Day Gift for Mom Her Grandma Birthday",
      "shop_name": "MignonandMignon",
      "advertised": true,
      "bestseller": false,
      "listing_id": "1244505971",
      "photo_link": "https://i.etsystatic.com/10158348/r/il/4e3c32/6569636808/il_794xN.6569636808_kwmx.jpg",
      "star_seller": true,
      "listing_link": "https://www.etsy.com/listing/1244505971/custom-name-necklace-for-women",
      "currency_code": "USD",
      "free_shipping": false,
      "original_price": 25,
      "discount_percent": 30,
      "shop_star_rating": 4.9,
      "number_of_reviews": 146996
    }
  ]
}
```

## Quick start

Call the API with a Fous API key (`FOUS_API_KEY`). To create one, turn on Developer mode in Fous Studio, then open Keys & connections → API keys (https://app.fous.com/keys).

```bash
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
: "${FOUS_API_KEY:?Set FOUS_API_KEY before running this example}"

curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 120 \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@etsy",
  "visibility": "public",
  "operation": "get_listing",
  "version": 1,
  "input": {
    "listing": "https://www.etsy.com/listing/1024603588/personalized-birth-flower-disc-necklace"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("FOUS_API_KEY")
if not api_key:
    raise RuntimeError("Set FOUS_API_KEY before running this example")

body = json.loads("{\n  \"api\": \"@etsy\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_listing\",\n  \"version\": 1,\n  \"input\": {\n    \"listing\": \"https://www.etsy.com/listing/1024603588/personalized-birth-flower-disc-necklace\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
// First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
const apiKey = process.env.FOUS_API_KEY;
if (!apiKey) throw new Error("Set FOUS_API_KEY before running this example");

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(120_000),
  body: JSON.stringify({
  "api": "@etsy",
  "visibility": "public",
  "operation": "get_listing",
  "version": 1,
  "input": {
    "listing": "https://www.etsy.com/listing/1024603588/personalized-birth-flower-disc-necklace"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

Or describe the data in plain language: send `{"api":"@etsy","prompt":"Describe the data you need, with every detail"}` to the same URL. Fous fills in the input, runs the method that fits and returns only the fields you asked for; `data.route.calls[].request` is the exact call it made. Routing is free; the run costs the same.

## Use cases

- Compare listing prices, ratings, shipping, and badges across search results
- Find items within a target price range
- Review item materials, variations, descriptions, and recent reviews
- Track a shop’s current listings, sales, and rating
- Check stated processing times and U.S. shipping estimates

## FAQ

### Is Fous affiliated with Etsy?

No. Fous is not affiliated with Etsy. This workflow reads the public etsy.com website and returns its data.

### How much does it cost?

Each run costs 1 credit. With pay-as-you-go, a credit costs 1¢; monthly plans cost less per credit.

### Do I need a Etsy account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from etsy.com when you run it; repeating the same request within a day may return the saved result. Fous checks this workflow automatically; it last passed a check on Sep 28, 2026.

### What listings match search words and a price range?

Search listings returns matching items with prices, shop ratings, shipping details, badges, ads, photos, and links.

### What are an item’s materials and variations?

Get listing returns item details including listed materials, selectable variations, description, photos, and recent reviews.

### What profile details and listings does a shop show?

Get shop returns the public shop profile and its current listings.

## Related

- [eBay API](https://fous.com/workflows/ebay.md): eBay provides listings, listing details, seller reputation and newest feedback; shipping varies by destination, and some details or counts may be missing or approximate.
- [Airbnb API](https://fous.com/workflows/airbnb.md): Airbnb returns public stays, listing details, dated trip prices, and night availability, which depend on dates and may be limited, unavailable, or change.
- [AliExpress API](https://fous.com/workflows/aliexpress.md): AliExpress returns product listings and selected product details, including prices, variants, reviews, and destination-specific shipping options shown for the displayed variant.
- [Craigslist API](https://fous.com/workflows/craigslist.md): Craigslist offers local ads and searches public listings newest by search order; available listing details omit hidden contacts, and renewals may have older dates.
- [Amazon API](https://fous.com/workflows/amazon.md): Amazon returns publicly shown product listings, prices, details, ratings, reviews, current best sellers, and Today's Deals; availability and content vary by store, location, and access.
- [OfferUp API](https://fous.com/workflows/offerup.md): Local marketplace for buying and selling items.
- [Mercari API](https://fous.com/workflows/mercari.md): Search secondhand and sold listings on Mercari US.
- [Walmart API](https://fous.com/workflows/walmart.md): Walmart helps shoppers find products from Walmart and marketplace sellers, view details, prices, ratings and reviews; availability uses Walmart’s default location, not ZIP codes.
- [All Commerce workflows](https://fous.com/workflows/category/commerce)