# Etsy Product Description

Retrieve detailed information about an Etsy product listing, including its title, description, images, pricing, variations, reviews, and more.

## Actor Statistics

- Total users: 11
- Monthly users: 2
- Runs succeeded: 54.32%
- Categories: E-commerce, SEO tools

## Pricing

$27.99/month + usage

## Input Schema

- **listingId** (type: string): The listingId to retrieve the description of.
- **currency** (type: string): The currency code.
- **language** (type: string): The language.
- **country** (type: string): The country.

## API example

## Etsy Product Description

- **OpenAPI Version:** `3.1.1`
- **API Version:** `1.0`

Retrieve detailed information about an Etsy product listing, including its title, description, images, pricing, variations, reviews, and more.

### Servers

- **URL:** `https://api.apify.com/v2`

### Operations

#### Executes an Actor, waits for its completion, and returns Actor's dataset items in response.

- **Method:** `POST`
- **Path:** `/acts/pintostudio~etsy-product-description/run-sync-get-dataset-items`
- **Tags:** Run Actor

##### Request Body

###### Content-Type: application/json

- **`listingId` (required)**

  `string` — The listingId to retrieve the description of.

- **`country`**

  `string` — The country.

- **`currency`**

  `string` — The currency code.

- **`language`**

  `string` — The language.

**Example:**

```
{
  "listingId": "",
  "currency": "",
  "language": "",
  "country": ""
}
```

##### Responses

###### Status: 200 OK

#### Executes an Actor and returns information about the initiated run in response.

- **Method:** `POST`
- **Path:** `/acts/pintostudio~etsy-product-description/runs`
- **Tags:** Run Actor

##### Request Body

###### Content-Type: application/json

- **`listingId` (required)**

  `string` — The listingId to retrieve the description of.

- **`country`**

  `string` — The country.

- **`currency`**

  `string` — The currency code.

- **`language`**

  `string` — The language.

**Example:**

```
{
  "listingId": "",
  "currency": "",
  "language": "",
  "country": ""
}
```

##### Responses

###### Status: 200 OK

\####### Content-Type: application/json

- **`data`**

  `object`

  - **`actId`**

    `string`

  - **`buildId`**

    `string`

  - **`buildNumber`**

    `string`

  - **`containerUrl`**

    `string`

  - **`defaultDatasetId`**

    `string`

  - **`defaultKeyValueStoreId`**

    `string`

  - **`defaultRequestQueueId`**

    `string`

  - **`finishedAt`**

    `string`, format: `date-time`

  - **`id`**

    `string`

  - **`meta`**

    `object`

    - **`origin`**

      `string`

    - **`userAgent`**

      `string`

  - **`options`**

    `object`

    - **`build`**

      `string`

    - **`diskMbytes`**

      `integer`

    - **`memoryMbytes`**

      `integer`

    - **`timeoutSecs`**

      `integer`

  - **`startedAt`**

    `string`, format: `date-time`

  - **`stats`**

    `object`

    - **`computeUnits`**

      `integer`

    - **`inputBodyLen`**

      `integer`

    - **`rebootCount`**

      `integer`

    - **`restartCount`**

      `integer`

    - **`resurrectCount`**

      `integer`

  - **`status`**

    `string`

  - **`usage`**

    `object`

    - **`ACTOR_COMPUTE_UNITS`**

      `integer`

    - **`DATA_TRANSFER_EXTERNAL_GBYTES`**

      `integer`

    - **`DATA_TRANSFER_INTERNAL_GBYTES`**

      `integer`

    - **`DATASET_READS`**

      `integer`

    - **`DATASET_WRITES`**

      `integer`

    - **`KEY_VALUE_STORE_LISTS`**

      `integer`

    - **`KEY_VALUE_STORE_READS`**

      `integer`

    - **`KEY_VALUE_STORE_WRITES`**

      `integer`

    - **`PROXY_RESIDENTIAL_TRANSFER_GBYTES`**

      `integer`

    - **`PROXY_SERPS`**

      `integer`

    - **`REQUEST_QUEUE_READS`**

      `integer`

    - **`REQUEST_QUEUE_WRITES`**

      `integer`

  - **`usageTotalUsd`**

    `number`

  - **`usageUsd`**

    `object`

    - **`ACTOR_COMPUTE_UNITS`**

      `integer`

    - **`DATA_TRANSFER_EXTERNAL_GBYTES`**

      `integer`

    - **`DATA_TRANSFER_INTERNAL_GBYTES`**

      `integer`

    - **`DATASET_READS`**

      `integer`

    - **`DATASET_WRITES`**

      `integer`

    - **`KEY_VALUE_STORE_LISTS`**

      `integer`

    - **`KEY_VALUE_STORE_READS`**

      `integer`

    - **`KEY_VALUE_STORE_WRITES`**

      `number`

    - **`PROXY_RESIDENTIAL_TRANSFER_GBYTES`**

      `integer`

    - **`PROXY_SERPS`**

      `integer`

    - **`REQUEST_QUEUE_READS`**

      `integer`

    - **`REQUEST_QUEUE_WRITES`**

      `integer`

  - **`userId`**

    `string`

**Example:**

```
{
  "data": {
    "id": "",
    "actId": "",
    "userId": "",
    "startedAt": "2025-01-08T00:00:00.000Z",
    "finishedAt": "2025-01-08T00:00:00.000Z",
    "status": "READY",
    "meta": {
      "origin": "API",
      "userAgent": ""
    },
    "stats": {
      "inputBodyLen": 2000,
      "rebootCount": 0,
      "restartCount": 0,
      "resurrectCount": 0,
      "computeUnits": 0
    },
    "options": {
      "build": "latest",
      "timeoutSecs": 300,
      "memoryMbytes": 1024,
      "diskMbytes": 2048
    },
    "buildId": "",
    "defaultKeyValueStoreId": "",
    "defaultDatasetId": "",
    "defaultRequestQueueId": "",
    "buildNumber": "1.0.0",
    "containerUrl": "",
    "usage": {
      "ACTOR_COMPUTE_UNITS": 0,
      "DATASET_READS": 0,
      "DATASET_WRITES": 0,
      "KEY_VALUE_STORE_READS": 0,
      "KEY_VALUE_STORE_WRITES": 1,
      "KEY_VALUE_STORE_LISTS": 0,
      "REQUEST_QUEUE_READS": 0,
      "REQUEST_QUEUE_WRITES": 0,
      "DATA_TRANSFER_INTERNAL_GBYTES": 0,
      "DATA_TRANSFER_EXTERNAL_GBYTES": 0,
      "PROXY_RESIDENTIAL_TRANSFER_GBYTES": 0,
      "PROXY_SERPS": 0
    },
    "usageTotalUsd": 0.00005,
    "usageUsd": {
      "ACTOR_COMPUTE_UNITS": 0,
      "DATASET_READS": 0,
      "DATASET_WRITES": 0,
      "KEY_VALUE_STORE_READS": 0,
      "KEY_VALUE_STORE_WRITES": 0.00005,
      "KEY_VALUE_STORE_LISTS": 0,
      "REQUEST_QUEUE_READS": 0,
      "REQUEST_QUEUE_WRITES": 0,
      "DATA_TRANSFER_INTERNAL_GBYTES": 0,
      "DATA_TRANSFER_EXTERNAL_GBYTES": 0,
      "PROXY_RESIDENTIAL_TRANSFER_GBYTES": 0,
      "PROXY_SERPS": 0
    }
  }
}
```

#### Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.

- **Method:** `POST`
- **Path:** `/acts/pintostudio~etsy-product-description/run-sync`
- **Tags:** Run Actor

##### Request Body

###### Content-Type: application/json

- **`listingId` (required)**

  `string` — The listingId to retrieve the description of.

- **`country`**

  `string` — The country.

- **`currency`**

  `string` — The currency code.

- **`language`**

  `string` — The language.

**Example:**

```
{
  "listingId": "",
  "currency": "",
  "language": "",
  "country": ""
}
```

##### Responses

###### Status: 200 OK

### Schemas

#### inputSchema

- **Type:**`object`

* **`listingId` (required)**

  `string` — The listingId to retrieve the description of.

* **`country`**

  `string` — The country.

* **`currency`**

  `string` — The currency code.

* **`language`**

  `string` — The language.

**Example:**

```
{
  "listingId": "",
  "currency": "",
  "language": "",
  "country": ""
}
```

#### runsResponseSchema

- **Type:**`object`

* **`data`**

  `object`

  - **`actId`**

    `string`

  - **`buildId`**

    `string`

  - **`buildNumber`**

    `string`

  - **`containerUrl`**

    `string`

  - **`defaultDatasetId`**

    `string`

  - **`defaultKeyValueStoreId`**

    `string`

  - **`defaultRequestQueueId`**

    `string`

  - **`finishedAt`**

    `string`, format: `date-time`

  - **`id`**

    `string`

  - **`meta`**

    `object`

    - **`origin`**

      `string`

    - **`userAgent`**

      `string`

  - **`options`**

    `object`

    - **`build`**

      `string`

    - **`diskMbytes`**

      `integer`

    - **`memoryMbytes`**

      `integer`

    - **`timeoutSecs`**

      `integer`

  - **`startedAt`**

    `string`, format: `date-time`

  - **`stats`**

    `object`

    - **`computeUnits`**

      `integer`

    - **`inputBodyLen`**

      `integer`

    - **`rebootCount`**

      `integer`

    - **`restartCount`**

      `integer`

    - **`resurrectCount`**

      `integer`

  - **`status`**

    `string`

  - **`usage`**

    `object`

    - **`ACTOR_COMPUTE_UNITS`**

      `integer`

    - **`DATA_TRANSFER_EXTERNAL_GBYTES`**

      `integer`

    - **`DATA_TRANSFER_INTERNAL_GBYTES`**

      `integer`

    - **`DATASET_READS`**

      `integer`

    - **`DATASET_WRITES`**

      `integer`

    - **`KEY_VALUE_STORE_LISTS`**

      `integer`

    - **`KEY_VALUE_STORE_READS`**

      `integer`

    - **`KEY_VALUE_STORE_WRITES`**

      `integer`

    - **`PROXY_RESIDENTIAL_TRANSFER_GBYTES`**

      `integer`

    - **`PROXY_SERPS`**

      `integer`

    - **`REQUEST_QUEUE_READS`**

      `integer`

    - **`REQUEST_QUEUE_WRITES`**

      `integer`

  - **`usageTotalUsd`**

    `number`

  - **`usageUsd`**

    `object`

    - **`ACTOR_COMPUTE_UNITS`**

      `integer`

    - **`DATA_TRANSFER_EXTERNAL_GBYTES`**

      `integer`

    - **`DATA_TRANSFER_INTERNAL_GBYTES`**

      `integer`

    - **`DATASET_READS`**

      `integer`

    - **`DATASET_WRITES`**

      `integer`

    - **`KEY_VALUE_STORE_LISTS`**

      `integer`

    - **`KEY_VALUE_STORE_READS`**

      `integer`

    - **`KEY_VALUE_STORE_WRITES`**

      `number`

    - **`PROXY_RESIDENTIAL_TRANSFER_GBYTES`**

      `integer`

    - **`PROXY_SERPS`**

      `integer`

    - **`REQUEST_QUEUE_READS`**

      `integer`

    - **`REQUEST_QUEUE_WRITES`**

      `integer`

  - **`userId`**

    `string`

**Example:**

```
{
  "data": {
    "id": "",
    "actId": "",
    "userId": "",
    "startedAt": "2025-01-08T00:00:00.000Z",
    "finishedAt": "2025-01-08T00:00:00.000Z",
    "status": "READY",
    "meta": {
      "origin": "API",
      "userAgent": ""
    },
    "stats": {
      "inputBodyLen": 2000,
      "rebootCount": 0,
      "restartCount": 0,
      "resurrectCount": 0,
      "computeUnits": 0
    },
    "options": {
      "build": "latest",
      "timeoutSecs": 300,
      "memoryMbytes": 1024,
      "diskMbytes": 2048
    },
    "buildId": "",
    "defaultKeyValueStoreId": "",
    "defaultDatasetId": "",
    "defaultRequestQueueId": "",
    "buildNumber": "1.0.0",
    "containerUrl": "",
    "usage": {
      "ACTOR_COMPUTE_UNITS": 0,
      "DATASET_READS": 0,
      "DATASET_WRITES": 0,
      "KEY_VALUE_STORE_READS": 0,
      "KEY_VALUE_STORE_WRITES": 1,
      "KEY_VALUE_STORE_LISTS": 0,
      "REQUEST_QUEUE_READS": 0,
      "REQUEST_QUEUE_WRITES": 0,
      "DATA_TRANSFER_INTERNAL_GBYTES": 0,
      "DATA_TRANSFER_EXTERNAL_GBYTES": 0,
      "PROXY_RESIDENTIAL_TRANSFER_GBYTES": 0,
      "PROXY_SERPS": 0
    },
    "usageTotalUsd": 0.00005,
    "usageUsd": {
      "ACTOR_COMPUTE_UNITS": 0,
      "DATASET_READS": 0,
      "DATASET_WRITES": 0,
      "KEY_VALUE_STORE_READS": 0,
      "KEY_VALUE_STORE_WRITES": 0.00005,
      "KEY_VALUE_STORE_LISTS": 0,
      "REQUEST_QUEUE_READS": 0,
      "REQUEST_QUEUE_WRITES": 0,
      "DATA_TRANSFER_INTERNAL_GBYTES": 0,
      "DATA_TRANSFER_EXTERNAL_GBYTES": 0,
      "PROXY_RESIDENTIAL_TRANSFER_GBYTES": 0,
      "PROXY_SERPS": 0
    }
  }
}
```

#### Etsy Product Description API Documentation

Retrieve detailed information about an Etsy product listing, including its title, description, images, pricing, variations, reviews, and more. This API is perfect for integrating Etsy product data into your applications, improving marketing campaigns, or powering ecommerce tools.

##### **Parameters**

| Name       | Type   | Description                          | Required | Default |
|------------|--------|--------------------------------------|----------|---------|
| `listingId` | String | Unique identifier for the Etsy product listing. | Yes      | N/A     |
| `currency`  | String | The currency for the product's price (e.g., USD). | No       | `USD`   |
| `language`  | String | Language code for the product description (e.g., `en-GB`). | No       | `en-GB` |
| `country`   | String | The country code (e.g., `US`).       | No       | `US`    |

***

##### **Example Response**

```json
{
  "title": "14K Solid Gold Family Birthstone Necklace, Birthstone Gift, Christmas Gift, Bridesmaid Gift, Gift for Mom, Birthday Gift, Birthstone Jewelry",
  "productId": "1301638116",
  "gtin": "n/a",
  "description": "Silver Birthstone Necklace, Personalized Gifts, 14k Solid Gold Birthstone Jewelry, Family Necklace For Grandmothers, Christmas Gift, Best Gifts for Mothers, Personalized Birthstone Necklace, Family Birthstone Necklace, Birthstone Gift, Dainty Necklace, Gift For Her, Birthday Gift\n\n☆ Back to my store for more options: https://www.etsy.com/shop/aceelegance\n\n☆ All the pieces you purchased from AceElegance come with a Certificate of Authenticity (925 Sterling Silver, 8k Solid Gold, 14k Solid Gold, 18k Solid Gold)\n\n☆ www.aceelegance.com ☆\n\n[...truncated for brevity...]",
  "images": [
    "https://i.etsystatic.com/27808603/r/il/17eff8/4476872409/il_fullxfull.4476872409_hru6.jpg",
    "https://i.etsystatic.com/27808603/r/il/dd8d66/4292154829/il_fullxfull.4292154829_7ikv.jpg",
    "https://i.etsystatic.com/27808603/r/il/0ba591/4244514176/il_fullxfull.4244514176_fm31.jpg",
    "https://i.etsystatic.com/27808603/r/il/abc9bc/4292145011/il_fullxfull.4292145011_thdf.jpg"
  ],
  "price": {
    "salePrice": "14.67",
    "originalPrice": "26.67",
    "currency": "$",
    "discount": "45% off"
  },
  "variations": [
    {
      "options1": [
        { "value": "2922229031", "text": "Silver-1 Birthstone ($18.33)" },
        { "value": "2922229041", "text": "Silver-2 Birthstones ($21.99)" }
      ]
    },
    {
      "options2": [
        { "value": "2922229033", "text": "14 Inches" },
        { "value": "2922229035", "text": "15 Inches" }
      ]
    }
  ],
  "category": [
    "Jewellery",
    "Necklaces",
    "Charm Necklaces"
  ],
  "brand": {
    "name": "AceElegance",
    "logo": "https://i.etsystatic.com/isla/e9d72e/60194815/isla_500x500.60194815_ndw6wt55.jpg?version=0"
  },
  "url": "https://www.etsy.com/listing/1301638116/14k-solid-gold-family-birthstone",
  "ratingSummary": {
    "ratingValue": "4.8",
    "reviewCount": 15678
  },
  "review": [
    {
      "@type": "Review",
      "reviewRating": {
        "@type": "Rating",
        "ratingValue": 5,
        "bestRating": 5
      },
      "datePublished": "2024-11-22",
      "reviewBody": "The necklace came in the cutest little packaging and was absolutely perfect. My grandmother is gonna love it",
      "author": {
        "@type": "Person",
        "name": "Raven Nellenback"
      }
    },
    {
      "@type": "Review",
      "reviewRating": {
        "@type": "Rating",
        "ratingValue": 5,
        "bestRating": 5
      },
      "datePublished": "2024-11-21",
      "reviewBody": "Cannot wait to give this to my mother in law for Christmas :)",
      "author": {
        "@type": "Person",
        "name": "Megan Marchase"
      }
    }
  ]
}
```

***

##### **Description of Response**

| Field          | Type       | Description                                                                                      |
|----------------|------------|--------------------------------------------------------------------------------------------------|
| `title`        | String     | The product's name or title.                                                                    |
| `productId`    | String     | Unique identifier for the product.                                                              |
| `gtin`         | String     | Global Trade Item Number if available.                                                          |
| `description`  | String     | Detailed description of the product.                                                            |
| `images`       | Array      | List of URLs for product images.                                                                |
| `price`        | Object     | Pricing information including sale and original prices, currency, and discount.                 |
| `variations`   | Array      | Available variations such as colors, sizes, or styles.                                          |
| `category`     | Array      | Hierarchical category for the product.                                                          |
| `brand`        | Object     | Brand details including name and logo.                                                          |
| `url`          | String     | Direct URL to the product page on Etsy.                                                         |
| `ratingSummary`| Object     | Summary of product ratings and total review count.                                              |
| `review`       | Array      | List of recent reviews with rating, date, content, and reviewer details.                        |

***

Here's an enhanced example of the Etsy Product Description API documentation, including a detailed description and FAQs with 10 questions and answers.

***

#### **Etsy Product Description API**

Retrieve detailed information about an Etsy product listing, including its title, description, images, pricing, variations, reviews, and more. This API is perfect for integrating Etsy product data into your applications, improving marketing campaigns, or powering ecommerce tools.

***

#### **Endpoint**

`GET /etsy-product-description`

***

#### **Parameters**

| Parameter   | Type   | Required | Default Value | Description                                                              |
|-------------|--------|----------|---------------|--------------------------------------------------------------------------|
| `listingId` | String | Yes      | N/A           | The unique ID of the Etsy product listing to retrieve information about. |
| `currency`  | String | No       | `USD`         | The currency format for the pricing information.                         |
| `language`  | String | No       | `en-GB`       | The language format for the returned data.                               |
| `country`   | String | No       | `US`          | The country format for the returned data.                                |

***

#### **Example Response**

```json
{
  "title": "14K Solid Gold Family Birthstone Necklace, Birthstone Gift, Christmas Gift, Bridesmaid Gift, Gift for Mom, Birthday Gift, Birthstone Jewelry",
  "productId": "1301638116",
  "gtin": "n/a",
  "description": "Silver Birthstone Necklace, Personalized Gifts, ...",
  "images": [
    "https://i.etsystatic.com/27808603/r/il/17eff8/4476872409/il_fullxfull.4476872409_hru6.jpg",
    "https://i.etsystatic.com/27808603/r/il/dd8d66/4292154829/il_fullxfull.4292154829_7ikv.jpg"
  ],
  "price": {
    "salePrice": "14.67",
    "originalPrice": "26.67",
    "currency": "$",
    "discount": "45% off"
  },
  "variations": [
    {
      "options1": [
        { "value": "2922229031", "text": "Silver-1 Birthstone ($18.33)" }
      ]
    }
  ],
  "category": ["Jewellery", "Necklaces", "Charm Necklaces"],
  "brand": {
    "name": "AceElegance",
    "logo": "https://i.etsystatic.com/isla/e9d72e/60194815/isla_500x500.60194815_ndw6wt55.jpg?version=0"
  },
  "url": "https://www.etsy.com/listing/1301638116/14k-solid-gold-family-birthstone",
  "ratingSummary": {
    "ratingValue": "4.8",
    "reviewCount": 15678
  },
  "review": [
    {
      "reviewRating": { "ratingValue": 5, "bestRating": 5 },
      "datePublished": "2024-11-22",
      "reviewBody": "The necklace came in the cutest little packaging...",
      "author": { "name": "Raven Nellenback" }
    }
  ]
}
```

***

This API provides detailed information about a specific Etsy product listing. With the listing ID as input, the API returns:

- Product title, description, and category hierarchy.
- High-quality images for the listing.
- Pricing details, including sale price, original price, currency, and discounts.
- Available variations, such as material, color, and size.
- Brand details, including name and logo.
- Reviews and ratings from customers.
- Product URL for direct navigation.

This API is suitable for building ecommerce aggregators, powering marketing tools, or enhancing customer engagement with accurate product details.

***

#### **FAQs**

1. **What is the purpose of the `listingId` parameter?**\
   The `listingId` identifies the specific Etsy product you want information about. It’s mandatory to ensure the API fetches the correct listing.

2. **Can I retrieve information in a different currency?**\
   Yes, use the `currency` parameter to specify the desired currency. For example, use `EUR` for Euros or `GBP` for British Pounds.

3. **What languages are supported?**\
   The API supports multiple languages. By default, it returns data in English (`en-GB`). Use the `language` parameter to set your preferred language.

4. **What happens if the `country` parameter is not specified?**\
   If not provided, the API defaults to `US`. This affects shipping information and localized data.

5. **Are the reviews limited in the response?**\
   The API typically returns the top 5 reviews. For more reviews, additional queries may be required.

6. **How are discounts calculated in the `price` object?**\
   Discounts are calculated based on the difference between `salePrice` and `originalPrice`. The `discount` field shows the percentage reduction.

7. **Can I use this API to list multiple Etsy products?**\
   Currently, the API supports fetching details for one product per request. Batch requests require individual calls.

8. **What happens if the listing ID is invalid or not found?**\
   The API returns an error message indicating the issue. Ensure the listing ID is correct and active.

9. **Are images returned in specific resolutions?**\
   Yes, the images are provided in high resolution, ideal for use in ecommerce platforms or marketing materials.

10. **How often is the data updated?**\
    The data reflects Etsy’s most recent updates. If changes occur on Etsy (e.g., price updates), they will appear in API responses shortly after.

***
