---
title: "Listings"
method: POST
path: "/listings"
tags: ["Market Data"]
---

# Listings

`POST /listings`

## Request

- Base URL: `https://external-api.wine-labs.com`
- URL: `https://external-api.wine-labs.com/listings`
- Auth: none declared

Retrieve active merchant offers with optional geography and packaging filters.

## Request body

- object
  - `query` string: Free-text wine description. Required when `lwin` is not provided.
  - `lwin` string: Direct LWIN lookup. Required when `query` is not provided.
  - `user_id` string, uuid, required: Account identifier issued during onboarding; used for authentication and quota tracking.
  - `currency` string: ISO currency code used for price conversion.
  - `region` string: Continent-level geography filter. Supported values: world, europe, north america, south america, africa, asia, oceania, australia (alias for oceania). Maps to a continent filter when explicit `continents` / `countries` are not provided.
  - `only_trusted_merchants` boolean: Filter to merchants designated as trusted partners.
  - `continents` string[]: Restrict listings to the provided continents.
  - `countries` string[]: Restrict listings to the provided countries. Accepts full names (e.g. "France") or ISO alpha-2/alpha-3 codes (e.g. "FR", "FRA"). Note: use "UK" or "GB" for the United Kingdom.
  - `standardized_formats` string[]: Filter by internal format labels (alias: `formats`). Allowed values: bottle, half-bottle, magnum, double-magnum.
  - `vintages` string[]: Filter to specific vintages.
  - `min_offer_volume` number: Minimum pack size filter (1–99). When absent and an 18-digit LWIN is provided, inferred from the LWIN case-size segment.
  - `max_offer_volume` number: Maximum pack size filter (1–99). When absent and an 18-digit LWIN is provided, inferred from the LWIN case-size segment.
  - `limit` number: Page size (1–20).
  - `offset` number: Pagination offset (>= 0).

## Response `200`

Response highlights:
- `lwin`: resolved LWIN used for the search.
- `limit`, `offset`, `count`, `has_more`: pagination metadata.
- `results[]`: array of merchant offers including pricing, merchant contact details, formats, and analytics flags.

Notes:
- Either `query` or `lwin` must be supplied.
- Extended LWINs auto-infer filters when explicit values are absent: 16+ digits can set `standardized_formats`; 18 digits can set `min_offer_volume` / `max_offer_volume`.
- Use `has_more` with `offset` to iterate through additional listings.
- Usage limit: up to 150,000 requests per rolling 30 days across Market Data endpoints.

- object

---

[API](https://skmtc.dev/winelabs/apis/wine-labs-api.md) · [All operations](https://skmtc.dev/winelabs/apis/wine-labs-api/llms.txt) · [OpenAPI document](https://skmtc.dev/winelabs/apis/wine-labs-api/revisions/f8898ca9974e?raw)