API Documentation

Explore authentication requirements, request payloads, and response structures for every Wine Labs API endpoint.

Filter by Section

Matching

Resolve free-text wine queries into LWIN codes and Wine Labs IDs for downstream workflows.

POST/match_to_lwinMatch To LWIN

Resolve a single wine search query to LWIN codes, a Wine Labs ID and a normalized display label.

Request Body

FieldTypeRequiredDefaultDescription
user_idstring (UUID)RequiredNoneAccount identifier issued during onboarding; used for authentication and quota tracking.
querystringOptionalNoneWine name, producer, vintage, or other descriptive text to resolve. Required when `lwin` and `wl_id` are not provided.
lwinstringOptionalNoneDirect LWIN lookup. Required when `query` and `wl_id` are not provided.
wl_idstringOptionalNoneWine Labs wine identifier. Required when `query` and `lwin` are not provided.

Response Highlights

  • `lwin7`: base 7-digit LWIN code when a match is found.
  • `lwin`: longest available LWIN including vintage or format detail.
  • `display_name`: normalized wine name suitable for customer-facing views.
  • `wl_id`: the Wine Labs ID, the canonical identifier covering 813K+ wines and spirits.
  • Returns null values for all fields when the query cannot be matched.
  • Usage limit: up to 30,000 matched rows per rolling 30 days across matching endpoints.

Wine Intelligence

Canonical wine profiles, classification, and reference data resolved from LWIN or free text.

POST/wine_infoWine Info

Retrieve canonical wine metadata including varietal, colour, and region details.

Request Body

FieldTypeRequiredDefaultDescription
user_idstring (UUID)RequiredNoneAuthorized user identifier used for authentication and rate limiting.
querystringOptionalNoneFree-text wine description. Required when `lwin` and `wl_id` are not provided.
lwinstringOptionalNoneDirect LWIN lookup. Required when `query` and `wl_id` are not provided.
wl_idstringOptionalNoneWine Labs wine identifier. Required when `query` and `lwin` are not provided.

Response Highlights

  • `lwin`: resolved LWIN echoed from the resolver.
  • `result`: canonical wine profile containing name, varietal, colour, wine or spirit classification, and regional hierarchy.
  • `result.avg_beg_drink_window` / `result.avg_end_drink_window`: average drinking-window years for the resolved vintage, or null when no vintage/window is available.
  • `result.is_kosher`: true only with recorded evidence for the resolved wine or vintage; null means unknown, not non-kosher. A vintage-specific request never inherits another vintage or producer-wide claim. Passover suitability and mevushal status are separate attributes.
  • At least one of `query`, `lwin`, or `wl_id` must be supplied.
  • Returns `result = null` when the resolver cannot map the wine to Wine Labs metadata.
POST/commodity_codesCommodity Codes

Classify wine, sparkling wine, grape must, other fermented beverages, and spirits into high-level HS and market-specific commodity code guidance.

Request Body

FieldTypeRequiredDefaultDescription
user_idstring (UUID)RequiredNoneAuthorized user identifier used for authentication and rate limiting.
querystringOptionalNoneFree-text product or wine description. Used with Wine Labs matching when provided.
lwinstringOptionalNoneDirect LWIN lookup for known wines.
wl_idstringOptionalNoneWine Labs wine identifier for known wines.
vintagestringOptionalNoneOptional vintage used when enriching known wine attributes.
product_type / commodity_type / hs_code_6stringOptionalNoneOptional classification hints when the product is not supplied as a known wine.
container_size_ml, abv, color, origin_country, destination_countrynumber/stringOptionalNoneOptional product attributes that improve jurisdiction-specific guidance.

Response Highlights

  • `hs_code_6`: resolved six-digit HS classification and display label.
  • `commodity_type`: Wine Labs high-level commodity category.
  • `jurisdiction_codes`: available resolved market codes, when they can be derived safely.
  • `country_code_systems[]`: market-by-market code systems, candidate patterns, and any attributes still needed for authority lookup.
  • At least one product identifier or classification hint is required.
  • Market-specific codes may be returned as candidate patterns when official authority lookup or additional product attributes are still required.

Market Data

Pricing snapshots and merchant availability for resolved wines.

POST/price_statsPrice Stats

Retrieve the latest aggregated pricing statistics for a wine in a target region.

Request Body

FieldTypeRequiredDefaultDescription
querystringOptionalNoneFree-text wine description. Required when `lwin` is not provided.
lwinstringOptionalNoneDirect LWIN lookup. Required when `query` is not provided.
regionstringOptionalworldTarget region alias. Supported values: world, europe, north america, south america, africa, asia, oceania.
currencystringOptionalUSDOptional output currency (uppercased) used for price conversion.
user_idstring (UUID)RequiredNoneAccount identifier issued during onboarding; used for authentication and quota tracking.

Response Highlights

  • `vintage`: vintage tied to the returned snapshot.
  • `region`: normalized region label from the request.
  • `lwin`: resolved LWIN when present.
  • `results[]`: array of pricing metrics (created_at, date, median_value, min, p25, p75, max, count, count_outliers, winelabs_price).
  • `results[].market_price_confidence`: high, medium, low, or null. Retail listing evidence only: high requires at least 20 listings and (p75 - p25) / median <= 0.25; medium requires at least 5 and <= 0.50; otherwise low. Missing or invalid evidence returns null. This describes listing depth and price agreement, not statistical probability, freshness, or independent seller count.
  • Returns an empty `results` array when no recent pricing is available for the selected wine and region.
  • Usage limit: up to 150,000 requests per rolling 30 days across Market Data endpoints.
POST/historical_price_statsHistorical Price Stats

Retrieve the historical time series of aggregated pricing statistics for a wine — one row per date (roughly the last 14 months) instead of the single latest snapshot returned by `/price_stats`.

Request Body

FieldTypeRequiredDefaultDescription
querystringOptionalNoneFree-text wine description. Required when `lwin` is not provided.
lwinstringOptionalNoneDirect LWIN lookup. Required when `query` is not provided.
regionstringOptionalworldTarget region alias. Supported values: world, europe, north america, south america, africa, asia, oceania.
currencystringOptionalUSDOptional output currency (uppercased) used for price conversion.
user_idstring (UUID)RequiredNoneAccount identifier issued during onboarding; used for authentication and quota tracking.

Response Highlights

  • `vintage`: vintage tied to the returned series.
  • `region`: normalized region label from the request.
  • `lwin`: resolved LWIN when present.
  • `results[]`: time series ordered by date — one entry per date (created_at, date, median_value, average, min, p25, p75, max, count, count_outliers, winelabs_price), covering roughly the last 14 months.
  • Same request shape as `/price_stats`; `/price_stats` returns the latest snapshot while `/historical_price_stats` returns the full dated history.
  • Returns an empty `results` array when no historical pricing is available for the selected wine and region.
  • Usage limit: up to 150,000 requests per rolling 30 days across Market Data endpoints.
POST/listingsListings

Retrieve active merchant offers with optional geography and packaging filters.

Request Body

FieldTypeRequiredDefaultDescription
querystringOptionalNoneFree-text wine description. Required when `lwin` is not provided.
lwinstringOptionalNoneDirect LWIN lookup. Required when `query` is not provided.
user_idstring (UUID)RequiredNoneAccount identifier issued during onboarding; used for authentication and quota tracking.
currencystringOptionalUSDISO currency code used for price conversion.
regionstringOptionalworldContinent-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_merchantsbooleanOptionalfalseFilter to merchants designated as trusted partners.
continentsarray<string>Optional[]Restrict listings to the provided continents.
countriesarray<string>Optional[]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_formatsarray<string>Optional[]Filter by internal format labels (alias: `formats`). Allowed values: bottle, half-bottle, magnum, double-magnum.
vintagesarray<string>Optional[]Filter to specific vintages.
min_offer_volumenumberOptionalNoneMinimum pack size filter (1–99). When absent and an 18-digit LWIN is provided, inferred from the LWIN case-size segment.
max_offer_volumenumberOptionalNoneMaximum pack size filter (1–99). When absent and an 18-digit LWIN is provided, inferred from the LWIN case-size segment.
limitnumberOptional20Page size (1–20).
offsetnumberOptional0Pagination offset (>= 0).

Response Highlights

  • `lwin`: resolved LWIN used for the search.
  • `limit`, `offset`, `count`, `has_more`: pagination metadata.
  • `results[]`: array of merchant offers including pricing, merchant names and websites, formats, and analytics flags. Street addresses and phone numbers are not returned.
  • 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.
POST/pricing_flow_pricePricing Flow Price

Execute your configured pricing flow (lowest priority when unspecified) using existing authorizations and credits; configure flows via Pricing Flow Builder.

Request Body

FieldTypeRequiredDefaultDescription
user_idstring (UUID)RequiredNoneAuthorized user identifier for pricing flows.
querystringOptionalNoneFree-text wine description; required when `lwin` is not provided.
lwinstringOptionalNoneDirect LWIN lookup; required when `query` is not provided.
vintagestringOptionalNoneOptional vintage to guide resolution and routing.
formatstringOptionalNoneBottle format hint used to route pricing logic.
conditionstringOptionalNoneBottle condition hint forwarded to the flow.
pack_sizenumberOptionalNonePack size (alias `packSize`) used for packaging adjustments.
currencystringOptionalUSDTarget currency for FX conversion; does not filter pricing sources.
flow_idstringOptionalNoneSpecific pricing flow to run; defaults to the lowest-priority flow when omitted.

Response Highlights

  • `flow_id`: pricing flow identifier executed for the request.
  • `price`, `bottle_price`, `adjusted_price`, `currency`: returned pricing with packaging adjustments when applicable.
  • `data_source`, `aggregation`: source and aggregation used to derive the price.
  • `applied_modifiers`, `path`: modifiers and routing path applied within the flow.
  • `resolved_lwin`, `resolved_vintage`: resolved wine context.
  • `confidence_score`, `record_count`: diagnostics for the derived price.
  • `format_detected`, `case_size_detected`: detected packaging cues from the request.
  • `trace`: per-node execution details including router matches and intermediate prices.
  • Provide either `query` or `lwin` to resolve the wine; flows return 404 when no wine or price can be derived.
  • Currency input only converts returned values; it never filters underlying records.
  • When `flow_id` is provided that specific flow is used; otherwise the user's lowest-priority pricing flow runs.
POST/shop_detailsShop Details

Retrieve detailed information about a retailer/shop by ID, or search for shops by name.

Request Body

FieldTypeRequiredDefaultDescription
user_idstring (UUID)RequiredNoneAuthorized user identifier used for authentication and rate limiting.
retailer_idnumberOptionalNoneThe retailer ID to look up. Required when not using search mode.
querystringOptionalNoneSearch query for shop names (minimum 3 characters). When provided, activates search mode.
limitnumberOptional10Maximum results returned in search mode.
offsetnumberOptional0Pagination offset for search mode.

Response Highlights

  • `retailer_id`: unique retailer identifier.
  • `shop_type`: type of shop (merchant, grocery, wine_shop).
  • `shop_name`: name of the shop/retailer.
  • `shop_country`: country where the shop is located.
  • `shop_state`: state/region where the shop is located.
  • `offers_count`: number of wine offers available from this retailer.
  • `shop_price_rating`: price competitiveness rating (higher = better prices).
  • `shop_diversity_rating`: inventory diversity rating (higher = more diverse selection).
  • In search mode: returns `results[]` array of shop details.
  • Either `retailer_id` or `query` must be provided.
POST/restaurant_detailsRestaurant Details

Find a restaurant by name and get its `restaurant_id`, or look up one restaurant by `restaurant_id`. Use the id with Restaurant Listings to pull that restaurant's wine list.

Request Body

FieldTypeRequiredDefaultDescription
user_idstring (UUID)RequiredNoneAuthorized user identifier used for authentication and rate limiting.
restaurant_idnumberOptionalNoneRestaurant identifier to look up. Returns one restaurant with full details. Required when `query` is not provided.
querystringOptionalNoneRestaurant name to search for (minimum 3 characters, for example `French Laundry`). Activates search mode. Required when `restaurant_id` is not provided.
citystringOptionalNoneNarrows a `query` to restaurants whose address contains this city.
statestringOptionalNoneNarrows a `query` by state or region.
countrystringOptionalNoneNarrows a `query` by country (`US`, `USA` and `United States` are treated the same).
michelin_starsnumberOptionalNoneNarrows a `query` to restaurants with exactly this many Michelin stars.
limitnumberOptional10Maximum results returned in search mode (1-20).
offsetnumberOptional0Pagination offset for search mode (0-200).

Response Highlights

  • Search mode returns `results[]`, each with only:
  • `restaurant_id`: identifier to pass to Restaurant Listings or back to this endpoint.
  • `has_wine_list`: whether Wine Labs holds a wine list for this restaurant.
  • Lookup by `restaurant_id` returns one object with `restaurant_id`, `restaurant_name`, `restaurant_country`, `restaurant_state`, `restaurant_website`, `restaurant_lat`, `restaurant_lng`, `offers_count`, `michelin_stars`, `has_wine_list`, `winelist_last_checked_at`. Street addresses and phone numbers are not returned.
  • Either `restaurant_id` or `query` must be provided. `city`, `state`, `country` and `michelin_stars` only narrow a `query`; they cannot be used on their own.
  • Search results are ordered by the number of wine list offers we hold, then Michelin stars, then name.
  • Uses the general details rate limits (a fraction of your market data quota).
POST/restaurant_listingsRestaurant Listings

Restaurant wine list offers, scoped to one restaurant (`restaurant_id`), one wine (`lwin` or `wl_id`), or a geography (city, state, or coordinates), with optional distance sorting from a coordinate pair.

Request Body

FieldTypeRequiredDefaultDescription
user_idstring (UUID)RequiredNoneAuthorized user identifier used for authentication and rate limiting.
restaurant_idnumberOptionalNoneReturn the wine list of one restaurant. Get the id from Restaurant Details. Sufficient on its own.
lwinstringOptionalNoneLWIN of one wine. Returns the restaurants that list that wine. An LWIN11 also filters the vintage. Sufficient on its own.
wl_idstringOptionalNoneWine Labs wine identifier. Same behaviour as `lwin`. Sufficient on its own.
citystringOptionalNoneCity name used to match restaurant addresses (for example, `New York` or `Paris`).
statestringOptionalNoneState filter for restaurant location. Accepts a 2-letter abbreviation or recognized full state name (for example, `CA` or `California`).
latnumberOptionalNoneLatitude of the search origin point. Must be provided together with `lng`.
lngnumberOptionalNoneLongitude of the search origin point. Must be provided together with `lat`.
max_distance_milesnumberOptional50Maximum search radius in miles when `lat`/`lng` are provided.
max_resultsnumberOptional20Page size (1-20). Use `offset` to page through a longer list.
offsetnumberOptional0Pagination offset. The response sets `has_more` when another page exists.
vintagearray<string>OptionalNoneOptional vintage filter (e.g., ["2015", "2016"]).
formatarray<string>OptionalNoneOptional bottle format filter (e.g., ["750ml", "1500ml"]).
countryarray<string>OptionalNoneOptional country filter for restaurant location.
continentarray<string>OptionalNoneOptional continent filter for restaurant location.
currencystringOptionalUSDOutput currency for wine price conversion.
include_unmatchedbooleanOptionaltrueSet to `false` to drop list lines we could not match to a Wine Labs wine.

Response Highlights

  • `city`, `state`, `lat`, `lng`: echoed filters when provided.
  • `currency`: applied currency for prices.
  • `has_more`: whether another page exists at `offset + max_results`.
  • `results[]`: array of restaurant listings, each containing:
  • `restaurant_id`, `restaurant_name`, `restaurant_country`, `restaurant_state`: restaurant identification. Street addresses and phone numbers are not returned.
  • `distance_miles`: distance from search origin when coordinates are provided.
  • `wine_name`, `wine_vintage`, `wine_price`, `wine_format`: wine listing details as printed on the list.
  • `wine_list_file_url`, `last_check_at`: the source wine list and when we last read it.
  • `is_outlier`: set when the price is far from the market for that wine.
  • Requires `markets` authorization. Uses the same rate limits as other market data endpoints.
  • At least one of `restaurant_id`, `lwin`, `wl_id`, `city`, `state`, or a full `lat`/`lng` pair is required.
  • Typical flow: call Restaurant Details with a name to get `restaurant_id`, then call this endpoint with that id.
  • `lat` and `lng` must be supplied together. When coordinates are provided, results are filtered and sorted by distance.

Auctions & Exchange

Self-serve and custom transaction datasets for auctions and exchange venues.

Auctions and exchange endpoints are available on self-serve plans, with custom access available for bespoke scopes, limits, and integrations.

Use the API pricing page for instant checkout, or contact us if you need a custom venue mix or higher-throughput package.

POST/auctionsAuctions

Access historical auction results from the supported self-serve auction dataset or your custom authorized scopes.

Request Body

FieldTypeRequiredDefaultDescription
user_idstring (UUID)RequiredNoneAuthorized user identifier used for plan-based authentication and quota tracking.
auction_provider_idsarray<number>Optional[]Filter results to specific auction providers.
querystringOptionalNoneFree-text wine description; optional when providing identifiers.
lwinstringOptionalNoneDirect LWIN filter.
vintagestringOptionalNoneVintage filter.
lot_idstringOptionalNoneInternal Wine Labs lot identifier.
auction_lot_idstringOptionalNoneProvider-specific lot identifier.
auction_idstring | numberOptionalNoneAuction event identifier.
sold_date_fromdate (YYYY-MM-DD)OptionalNoneInclusive lower bound for sold date.
sold_date_todate (YYYY-MM-DD)OptionalNoneInclusive upper bound for sold date.
limitnumberOptional10Page size (1–100).
offsetnumberOptional0Pagination offset (>= 0).
sort_bystringOptionalsold_dateSort options: sold_date, auction_date, hammer_price_usd, realised_price_usd, bottle_price_usd, auction_id.
sort_directionstringOptionaldescSort direction: asc or desc.

Response Highlights

  • `limit`, `offset`, `count`, `total_available`: pagination metadata.
  • `results[]`: auction lots with provider info, hammer prices (native and USD), bottle price, currency, and resolved wine identifiers.
  • Self-serve auction plans include every supported auction house. Sotheby’s, Interenchères and Heritage Auctions results cover sales held in the last 365 days.
  • Usage limits depend on your active auction subscription and renew each billing cycle.
  • Custom plans are available when you need bespoke scopes, limits, or integration support.
POST/exchange/orderbookExchange Orderbook

Retrieve current bids and offers from the supported self-serve exchange venues or your custom authorized sources.

Request Body

FieldTypeRequiredDefaultDescription
user_idstring (UUID)RequiredNoneAuthorized user identifier used for plan-based authentication and quota tracking.
querystringOptionalNoneFree-text wine description; optional when identifiers are provided.
lwinstringOptionalNoneDirect LWIN filter.
vintagestringOptionalNoneVintage filter.
sourcesarray<string>Optional[]Restrict results to specific exchange sources.
bid_askstringOptionalNoneUse "BID" or "ASK" to return only bids or asks.
formatstringOptionalNoneBottle format filter.
conditionstringOptionalNoneCondition filter.
packagingstringOptionalNonePackaging filter.
duty_codestringOptionalNoneDuty status filter (e.g., IB, DP).
currency_codestringOptionalNoneOptional target currency for FX conversion; does not filter order book rows by currency.
limitnumberOptional10Page size (1–100).
offsetnumberOptional0Pagination offset (>= 0).
sort_bystringOptionalpriceSort options: price, source, bid_ask, volume, currency_code.
sort_directionstringOptionalascSort direction: asc or desc.

Response Highlights

  • `limit`, `offset`, `count`, `total_available`: pagination metadata.
  • `results[]`: order book entries with provider identifiers, wine details, side (bid/ask), volume, price, currency, condition, packaging, duty status, and display name.
  • Currency inputs convert returned prices only; they never filter which orders are returned.
  • Self-serve exchange plans include `bordeaux_index`, `winebourse`, `cru_world_wine`, `cultx`, `cult_wines`, `vinovest`, `bbx`, and `arvest_wine`.
  • Transactions API includes auctions, exchange trades, and exchange order book under one shared allowance. All exchanges except Liv-ex are included. Legacy Exchange Endpoints subscriptions retain their original split allowances.
  • Custom plans are available if you need additional venues, custom scopes, or higher throughput.
POST/exchange/tradesExchange Trades

Retrieve historical executed trades from the supported self-serve exchange venues or your custom authorized sources.

Request Body

FieldTypeRequiredDefaultDescription
user_idstring (UUID)RequiredNoneAuthorized user identifier used for plan-based authentication and quota tracking.
querystringOptionalNoneFree-text wine description; optional when identifiers are provided.
lwinstringOptionalNoneDirect LWIN filter.
vintagestringOptionalNoneVintage filter.
sourcesarray<string>Optional[]Restrict results to specific exchange sources.
formatstringOptionalNoneBottle format filter.
conditionstringOptionalNoneCondition filter.
packagingstringOptionalNonePackaging filter.
duty_codestringOptionalNoneDuty status filter (e.g., IB, DP).
currency_codestringOptionalNoneOptional target currency for FX conversion; does not filter trades by currency.
traded_at_fromISO 8601 datetimeOptionalNoneInclusive lower bound for trade timestamp.
traded_at_toISO 8601 datetimeOptionalNoneInclusive upper bound for trade timestamp.
limitnumberOptional100Page size (1–100).
offsetnumberOptional0Pagination offset (>= 0).
sort_bystringOptionaltraded_atSort options: traded_at, price, source, volume.
sort_directionstringOptionaldescSort direction: asc or desc.

Response Highlights

  • `limit`, `offset`, `count`, `total_available`: pagination metadata.
  • `results[]`: executed trades with trade identifiers, provider context, wine identifiers, price, currency, volume, condition, packaging, duty status, and execution timestamp.
  • Self-serve exchange plans include `bordeaux_index`, `winebourse`, `cru_world_wine`, `cultx`, `cult_wines`, `vinovest`, `bbx`, and `arvest_wine`.
  • Transactions API includes auctions, exchange trades, and exchange order book under one shared allowance. All exchanges except Liv-ex are included. Legacy Exchange Endpoints subscriptions retain their original split allowances.
  • Use `traded_at_from` and `traded_at_to` to constrain the time horizon of results.
  • Custom plans are available if you need additional venues, custom scopes, or higher throughput.
POST/transactionsTransactions

Retrieve historical transaction data across the auction and exchange scopes available to your self-serve or custom access package.

Request Body

FieldTypeRequiredDefaultDescription
user_idstring (UUID)RequiredNoneAuthorized user identifier used for plan-based authentication and quota tracking.
auction_provider_idsarray<number>Optional[]Optional auction-provider filter for transaction feeds that include auction venues.
querystringOptionalNoneFree-text wine description; optional when identifiers are provided.
lwinstringOptionalNoneDirect LWIN filter.
lwinsarray<string>Optional[]Batch list of LWIN values when requesting multiple wines in one call.
vintagestringOptionalNoneVintage filter.
queriesarray<string>Optional[]Batch list of free-text wine queries when requesting multiple wines in one call.
sourcesarray<string>Optional[]Restrict results to specific exchange sources.
formatstringOptionalNoneBottle format filter.
conditionstringOptionalNoneCondition filter.
packagingstringOptionalNonePackaging filter.
duty_codestringOptionalNoneDuty status filter (e.g., IB, DP).
currency_codestringOptionalNoneOptional target currency for FX conversion; does not filter trades by currency.
traded_at_fromISO 8601 datetimeOptionalNoneInclusive lower bound for trade timestamp.
traded_at_toISO 8601 datetimeOptionalNoneInclusive upper bound for trade timestamp.
limitnumberOptional100Page size (1–100).
offsetnumberOptional0Pagination offset (>= 0).
sort_bystringOptionaltraded_atSort options: traded_at, price, source, volume.
sort_directionstringOptionaldescSort direction: asc or desc.

Response Highlights

  • `limit`, `offset`, `count`, `total_available`: pagination metadata.
  • `results[]`: executed trades with trade identifiers, provider context, wine identifiers, price, currency, volume, condition, packaging, duty status, and execution timestamp.
  • Transactions access follows the same self-serve and custom authorization rules as the auctions and exchange endpoints above.
  • Transactions API shares one monthly allowance across auctions, exchange trades, and exchange order book. The combined /transactions endpoint counts once per wine, without billing its internal auction and trade calls again. Batch requests count per wine. All auction houses and exchanges except Liv-ex are included. Sotheby’s, Interenchères and Heritage Auctions results cover sales held in the last 365 days.
  • Use `query`/`lwin` for a single wine request, or `queries`/`lwins` for multi-wine batch style requests.
  • Use `traded_at_from` and `traded_at_to` to constrain the time horizon of results.

Market Insights

Authorized historical pricing and alerting for market participants.

Market insights endpoints require a custom contract and explicit authorization from Wine Labs.

Contact us to configure access to specific venues, providers, and data scopes before integrating.

POST/price_historyPrice History

Return aggregated price history for a resolved wine with client-friendly caching and currency conversion.

Request Body

FieldTypeRequiredDefaultDescription
querystringOptionalNoneFree-text wine description. Required when `lwin` is not provided.
lwinstringOptionalNoneDirect LWIN lookup. Required when `query` is not provided.
user_idstring (UUID)RequiredNoneAuthorized user identifier (accepts `user_id` or `userId`) required for market_insights access.
regionstringOptionalworldRegion alias. Supported values: world, europe, north america, south america, africa, asia, oceania, uk, united kingdom, continental europe.
vintagestringOptionalALLVintage filter; use ALL to include every vintage.
currencystringOptionalUSDOutput currency (uppercased) for price conversion.
start_datestring (YYYY-MM-DD)OptionalNoneInclusive start date filter; rejected when the format is invalid or if it is later than `end_date`.
end_datestring (YYYY-MM-DD)OptionalNoneInclusive end date filter; validated against `start_date` and forwarded to the SQL query.
limitnumberOptional10Rows per page (clamped 1–100), ordered by newest date first.
offsetnumberOptional0Pagination offset (>= 0).

Response Highlights

  • `history[]`: reverse-chronological price history data with converted prices.
  • `regions`: static list of available region aliases for selection.
  • Requires market_insights authorization plus either `query` or `lwin`; unresolved wines return 404.
  • `start_date`/`end_date` are parsed and logged with the request metadata, and rejected when invalid or when `start_date` is later than `end_date`.
POST/trade_signalsTrade Signals

Return price movement alerts for a wine with optional geography, format, and change-type filters.

Request Body

FieldTypeRequiredDefaultDescription
querystringOptionalNoneFree-text wine description. Required when `lwin` is not provided.
lwinstringOptionalNoneDirect LWIN lookup. Required when `query` is not provided.
userIdstring (UUID)RequiredNoneAuthorized user identifier required for market_insights access.
regionstringOptionalworldContinent-level geography filter; overrides `continents` when provided. Supported values: world, europe, north america, south america, africa, asia, oceania.
currencystringOptionalUSDOutput currency (uppercased) for price conversion.
onlyTrustedMerchantsbooleanOptionalfalseFilter results to trusted merchants only.
continentsarray<string>OptionalNoneGeographic filter applied when `region` is not set.
countriesarray<string>OptionalNoneRestrict results 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.
formatsarray<string>OptionalNoneStandardized format filters (e.g., bottle sizes).
vintagesarray<string>OptionalNoneFilter to specific vintages.
changeTypesarray<string>Optional["removed"]Types of changes to surface (e.g., removed, increased, decreased).
sincestringOptionalNoneLower bound timestamp for detected changes.
lastOnlybooleanOptionaltrueReturn only the latest signal per location when true.
limitnumberOptional10Rows per page (clamped 1–10).
offsetnumberOptional0Pagination offset (>= 0).
minPercentChangenumberOptional3Minimum percent change threshold; defaults to 3 when unset or non-finite.

Response Highlights

  • `data[]`: trade signal entries with merchant and location metadata.
  • Requires market_insights authorization plus either `query` or `lwin`; unresolved wines return 404.

Custom Feed

Aggregated reporting for custom uploads using existing authentication and credits.

POST/custom_feed/transactionsCustom Transactions

Fetch aggregated custom transactions using existing authentication and credits.

Request Body

FieldTypeRequiredDefaultDescription
user_idstring (UUID)RequiredNoneAuthorized user identifier for the custom feed dataset.
agg_levelstringOptionalvintageAggregation level; allowed values: vintage, format, volume.
currencystringOptionalNoneOptional target currency for FX conversion only; it does not filter the results.
page_limitnumberOptional50 (max 500)Rows per page; clamped between 1 and 500.
page_offsetnumberOptional0Pagination offset (>= 0).
querystringOptionalNoneFree-text wine description used when resolving without `lwin`.
lwinstringOptionalNoneDirect LWIN filter; optional when `query` is provided.
wine_searchstringOptionalNoneSearch string applied to stored wine names.
sort_colstringOptionalNoneOptional sort column for the aggregation.
vintagesarray<string>OptionalNoneFilter to specific vintages.
formatsarray<number>OptionalNoneFilter to bottle formats by milliliter value.
volumesarray<number>OptionalNoneFilter to specific volumes.

Response Highlights

  • `limit`, `offset`, `count`: pagination metadata echoed from the service.
  • `results[]`: aggregated custom transaction rows.
  • `results[]` fields include `id`, `created_at`, `upload_id`, `wine_name`, `vintage`, `format`, `volume`, `raw_format`, `bottle_price`, `price`, `matching_attempted`, `offer_type`, `condition`, `packaging`, `quantity`, `ordered_at`, `source_id`, `user_id`, `currency_code`, `expiration_date`, `source_name`, `email_address`.
  • Currency input converts returned prices only; it never filters the underlying custom rows.
POST/custom_feed/price_listCustom Price List

Fetch aggregated custom offers/price lists using existing authentication and credits.

Request Body

FieldTypeRequiredDefaultDescription
user_idstring (UUID)RequiredNoneAuthorized user identifier for the custom feed dataset.
agg_levelstringOptionalvintageAggregation level; allowed values: vintage, format, volume.
currencystringOptionalNoneOptional target currency for FX conversion only; it does not filter the results.
page_limitnumberOptional50 (max 500)Rows per page; clamped between 1 and 500.
page_offsetnumberOptional0Pagination offset (>= 0).
querystringOptionalNoneFree-text wine description used when resolving without `lwin`.
lwinstringOptionalNoneDirect LWIN filter; optional when `query` is provided.
wine_searchstringOptionalNoneSearch string applied to stored wine names.
sort_colstringOptionalNoneOptional sort column for the aggregation.
vintagesarray<string>OptionalNoneFilter to specific vintages.
formatsarray<number>OptionalNoneFilter to bottle formats by milliliter value.
volumesarray<number>OptionalNoneFilter to specific volumes.

Response Highlights

  • `limit`, `offset`, `count`: pagination metadata echoed from the service.
  • `results[]`: aggregated custom price list rows.
  • `results[]` fields include `id`, `created_at`, `upload_id`, `wine_name`, `vintage`, `format`, `volume`, `raw_format`, `bottle_price`, `price`, `matching_attempted`, `source_id`, `user_id`, `currency_code`, `expiration_date`, `source_name`, `email_address`.
  • Currency input converts returned prices only; it never filters the underlying custom rows.
POST/pricing_flow_pricePricing Flow Price

Execute the user’s pricing flow (lowest priority when unspecified) using existing authorizations and credits; configure flows via Pricing Flow Builder.

Request Body

FieldTypeRequiredDefaultDescription
user_idstring (UUID)RequiredNoneAuthorized user identifier for pricing flows.
querystringOptionalNoneFree-text wine description; required when `lwin` is not provided.
lwinstringOptionalNoneDirect LWIN lookup; required when `query` is not provided.
vintagestringOptionalNoneOptional vintage to guide resolution and routing.
formatstringOptionalNoneBottle format hint used to route pricing logic.
conditionstringOptionalNoneBottle condition hint forwarded to the flow.
pack_sizenumberOptionalNonePack size (alias `packSize`) used for packaging adjustments.
currencystringOptionalUSDTarget currency for FX conversion; does not filter pricing sources.
flow_idstringOptionalNoneSpecific pricing flow to run; defaults to the lowest-priority flow when omitted.

Response Highlights

  • `flow_id`: pricing flow identifier executed for the request.
  • `price`, `bottle_price`, `adjusted_price`, `currency`: returned pricing with packaging adjustments when applicable.
  • `data_source`, `aggregation`: source and aggregation used to derive the price.
  • `applied_modifiers`, `path`: modifiers and routing path applied within the flow.
  • `resolved_lwin`, `resolved_vintage`: resolved wine context.
  • `confidence_score`, `record_count`: diagnostics for the derived price.
  • `format_detected`, `case_size_detected`: detected packaging cues from the request.
  • `trace`: per-node execution details including router matches and intermediate prices.
  • Provide either `query` or `lwin` to resolve the wine; flows return 404 when no wine or price can be derived.
  • Currency input only converts returned values; it never filters underlying records.
  • When `flow_id` is provided that specific flow is used; otherwise the user’s lowest-priority pricing flow runs.

Product feedback

Report a problem with Wine Labs or suggest an improvement. Agents can send feedback directly from any HTTP client.

POSThttps://winelabs.ai/api/feedbackSubmit product feedback

Send JSON to the Wine Labs feedback inbox. No API key or credits are required. Describe what happened and what you expected. Omit personal details, credentials and chat transcripts.

{
  "type": "bug",
  "description": "Selecting EUR still displays prices in USD."
}

Request Body

FieldTypeRequiredDefaultDescription
typestringRequiredNoneChoose bug, feature, improvement, or general.
descriptionstringRequiredNoneA nonblank report of up to 2,000 characters.

Response Highlights

  • HTTP 201 confirms receipt. Save data.id as the feedback reference.
  • Send each report once. If you receive HTTP 429, wait 15 minutes before trying again.