# Vinted Item

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/vinted/item` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/vinted-item |

## Description

Fetch a Vinted listing by item URL or numeric ID. Parses the public item page (Next.js payload), returns a normalized snake_case object with photos, attributes, shipping, pricing, and optional seller profile.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/vinted/item' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Item on vinted.com (Purple prom dress)

```json
{
  "id": 9437210920,
  "url": "https://www.vinted.com/items/9437210920-purple-prom-dress",
  "user": {
    "id": 3163220665,
    "city": "CHAMBERSBURG, PA",
    "login": "gingertastic88",
    "photo": {
      "id": 317632205,
      "url": "https://images1.vinted.net/t/01_00734_TjeYgCPBFTM9wAukJhk91fHm/f800/1781705165.webp?s=996d52a34c31e60e6cad8c3ad1d0bd504928d6e8",
      "width": 96,
      "height": 96
    },
    "business": false,
    "item_count": 10,
    "profile_url": "https://www.vinted.com/member/3163220665-gingertastic88",
    "country_code": "US",
    "verification": {
      "email": {
        "valid": true,
        "available": true
      },
      "google": {
        "valid": true,
        "available": true,
        "verified_at": "2026-06-17T08:06:05-06:00"
      }
    },
    "country_title": "United States",
    "feedback_count": 1,
    "feedback_reputation": 1,
    "positive_feedback_count": 1
  },
  "color": "Purple",
  "price": {
    "amount": "9.0",
    "currency_code": "USD"
  },
  "title": "Purple prom dress",
  "photos": [
    {
      "id": 39947998424,
      "url": "https://images1.vinted.net/t/03_01b9c_waHhWwt2YUWWt6mHUEY8DPbs/f800/1784471551.webp?s=895a7ec5100a7bc29e98d171869c4c1ab510ac13",
      "width": 600,
      "height": 800,
      "is_main": true,
      "full_size_url": "https://images1.vinted.net/tc/03_01b9c_waHhWwt2YUWWt6mHUEY8DPbs/1784471551.webp?s=e1d11e587899e731615fee24ed0c6cd41d6ab0fe"
    }
  ],
  "status": "New without tags",
  "can_buy": true,
  "plugins": {
    "favourite": {
      "seller_id": 3163220665,
      "is_favourite": false,
      "favourite_count": 0
    },
    "breadcrumbs": {
      "brand_id": 1,
      "catalog_id": 1777,
      "breadcrumbs": [
        {
          "url": "/catalog/1904-women",
          "title": "Women"
        },
        {
          "url": "/catalog/4-clothing",
          "title": "Clothing"
        },
        {
          "url": "/catalog/10-dresses",
          "title": "Dresses"
        },
        {
          "url": "/catalog/1774-special-occasion-dresses",
          "title": "Special-occasion dresses"
        },
        {
          "url": "/catalog/1777-prom-dresses",
          "title": "Prom dresses"
        }
      ]
    },
    "description": {
      "description": "Long purple prom dress, one strap"
    },
    "item_status": {
      "is_draft": false,
      "promoted": true,
      "is_closed": false,
      "is_hidden": false,
      "is_reserved": false,
      "transaction_permitted": true
    }
  },
  "brand_id": 1,
  "category": "Women Prom dresses",
  "promoted": true,
  "seller_id": 3163220665,
  "attributes": {
    "size": {
      "id": 506,
      "value": "S / US 4-6"
    },
    "color": "Purple",
    "status": {
      "id": 50,
      "value": "New without tags"
    },
    "upload_date": "an hour ago"
  },
  "catalog_id": 1777,
  "size_title": "S / US 4-6",
  "description": "Long purple prom dress, one strap",
  "instant_buy": true,
  "uploaded_at": "an hour ago",
  "is_favourite": false,
  "favourite_count": 0,
  "pricing_services": {
    "services": {
      "shipping": {
        "type": "shipping",
        "is_free": true,
        "final_price": {
          "amount": "0",
          "currency_code": "USD"
        },
        "original_price": {
          "amount": "6.69",
          "currency_code": "USD"
        }
      },
      "buyer_protection": {
        "type": "buyer_protection",
        "is_free": false,
        "final_price": {
          "amount": "1.15",
          "currency_code": "USD"
        },
        "original_price": {
          "amount": "1.15",
          "currency_code": "USD"
        }
      }
    },
    "total_amount": {
      "amount": "10.15",
      "currency_code": "USD"
    },
    "original_asking_amount": {
      "amount": "9",
      "currency_code": "USD"
    }
  },
  "shipping_details": {
    "price": {
      "amount": "0",
      "currency_code": "USD"
    },
    "discount": null,
    "is_pickup_only": false,
    "is_free_shipping": true,
    "are_multiple_shipping_options_available": false
  }
}
```

## Documentation

## Overview
Fetch a single Vinted listing by item URL or numeric ID.

- **Search** and **[Vinted User Info](/v2/vinted/user/info)** call the internal Vinted API v2 (`/api/v2/...`) with an auto-managed session.
- **Item** loads the **public HTML page** (`/items/{id}`). The legacy JSON endpoint `/api/v2/items/{id}` returns 404.

Piloterr parses the embedded Next.js payload, normalizes all keys to `snake_case`, and optionally enriches the response with the seller profile via `/api/v2/users/{seller_id}`.

Costs **1 credit** per call.

## Workflow
1. **[Vinted Search](/v2/vinted/search)** to find listings
2. **Item** (this endpoint) for the full normalized page payload + seller snapshot
3. **[Vinted User Info](/v2/vinted/user/info)** when you only have a member ID/URL

## Quickstart
```
GET https://api.piloterr.com/v2/vinted/item?query=https://www.vinted.com/items/9437210920-purple-prom-dress
GET https://api.piloterr.com/v2/vinted/item?query=9437210920&region=com
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Item URL or numeric item ID |
| `region` | string | no | Force domain when `query` is a bare ID (`com`, `https://www.vinted.de`, …) |

## Response
Dynamic extraction from the Next.js payload: all item-linked Vinted plugins are collected, keys normalized to `snake_case`, and new sidebar attributes are supported automatically.

```json
{
  "id": 9437210920,
  "title": "Purple prom dress",
  "description": "Long purple prom dress, one strap",
  "url": "https://www.vinted.com/items/9437210920-purple-prom-dress",
  "price": { "amount": "9.0", "currency_code": "USD" },
  "photos": [{ "id": 39947998424, "url": "...", "is_main": true, "full_size_url": "..." }],
  "seller_id": 3163220665,
  "size_title": "S / US 4-6",
  "status": "New without tags",
  "color": "Purple",
  "uploaded_at": "an hour ago",
  "attributes": {
    "size": { "value": "S / US 4-6", "id": 506 },
    "status": { "value": "New without tags", "id": 50 },
    "color": "Purple"
  },
  "favourite_count": 0,
  "catalog_id": 1777,
  "shipping_details": { "is_free_shipping": true, "price": { "amount": "0", "currency_code": "USD" } },
  "pricing_services": {
    "total_amount": { "amount": "10.15", "currency_code": "USD" },
    "services": { "buyer_protection": { "final_price": { "amount": "1.15", "currency_code": "USD" } } }
  },
  "plugins": {
    "breadcrumbs": { "catalog_id": 1777, "breadcrumbs": [{ "title": "Women", "url": "/catalog/1904-women" }] },
    "favourite": { "favourite_count": 0, "is_favourite": false }
  },
  "user": { "id": 3163220665, "login": "gingertastic88", "profile_url": "...", "item_count": 10 }
}
```

### Normalization
- All keys are `snake_case` (`isFreeShipping` → `is_free_shipping`, `currencyCode` → `currency_code`).
- Core RSC item object + every plugin linked to the item (`"name"`, `"type"`, …).
- Sidebar attributes → `attributes.{code}`; scalar values also promoted to top-level (`size` → `size_title`, `upload_date` → `uploaded_at`; other codes like `material` keep their name).
- Each plugin is also stored under `plugins.{name}`; useful scalars are hoisted to top-level (`favourite_count`, `description`, …). Generic keys `name`, `type`, `section` are not hoisted.
- `shipping_details` and `pricing_services` are read next to the core item object.
- JSON-LD (`schema.org/Product`) fills missing fields only (title, price, url, photos, …).
- `user` is fetched from `/api/v2/users/{seller_id}` when available; if the user API fails, the item is still returned without `user`.

| Field | Description |
|---|---|
| `id` / `url` / `title` | Item identity |
| `description` | Seller-written description |
| `price.amount` / `price.currency_code` | Listing price |
| `photos[]` | Image gallery |
| `attributes` | Raw sidebar attributes by code |
| `size_title` / `status` / `color` / `uploaded_at` | Promoted attribute aliases |
| `shipping_details` | Shipping options |
| `pricing_services` | Buyer protection + shipping breakdown |
| `plugins` | Raw plugin payloads (`breadcrumbs`, `favourite`, …) |
| `catalog_id` / `seller_id` | Internal Vinted IDs |
| `favourite_count` | Number of favourites |
| `user` | Seller profile when the user API succeeds |

### Search vs Item
| Search (API v2 catalog) | Item (HTML page) |
|---|---|
| `photo` (main image) | `photos[]` gallery |
| `service_fee` / `total_item_price` | `pricing_services` |
| `user` (light snapshot) | `user` (full profile, optional) |
| Fixed catalog card shape | `attributes`, `plugins`, dynamic sidebar fields |

## Error codes
| Code | Cause |
|---|---|
| `400` | Item ID could not be parsed from `query` |
| `404` | Item not found on any tested Vinted domain |
| `403` | Page blocked (anti-bot) |

## Good to know
- **Full item URL** is the fastest input: domain is taken from the URL.
- **Bare numeric ID**: tries `vinted.fr`, `vinted.com`, `vinted.de`, `vinted.es`, `vinted.it`, `vinted.pl`, `vinted.nl`, `vinted.be`, and `vinted.co.uk`.
- Pass `region` with a bare ID to skip the multi-domain lookup.
- `user` may be absent if the seller API errors; the item payload is still returned.
- Public listing data only.

## Main use cases
- Enrich Search results with description, attributes, shipping, and pricing breakdown
- Fetch seller profile alongside item details in one call
- Resale analytics on individual listings