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 identifiers for downstream workflows.

POST/match_to_lwinMatch To LWIN

Resolve a single wine search query to LWIN codes and a normalized display label.

Request Body

Field	Type	Required	Default	Description
user_id	string (UUID)	Required	None	Account identifier issued during onboarding; used for authentication and quota tracking.
query	string	Optional	None	Wine name, producer, vintage, or other descriptive text to resolve. Required when `lwin` and `wl_id` are not provided.
lwin	string	Optional	None	Direct LWIN lookup. Required when `query` and `wl_id` are not provided.
wl_id	string	Optional	None	Wine 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.

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

Critic reviews and canonical wine profiles resolved from external critic identifiers.

POST/critic_scoresCritic Scores

Return structured critic ratings filtered by wine, vintage, and critic name.

Request Body

Field	Type	Required	Default	Description
user_id	string (UUID)	Required	None	Authorized user identifier used for authentication and rate limiting.
query	string	Optional	None	Free-text wine description. Required when `lwin` and `wl_id` are not provided.
lwin	string	Optional	None	Direct LWIN lookup. Required when `query` and `wl_id` are not provided.
wl_id	string	Optional	None	Wine Labs wine identifier. Required when `query` and `lwin` are not provided.
vintage	string	Optional	None	Optional vintage filter; use `ALL` to include every vintage.
critic_wl_id	array<number>	Optional	None	Optional list of Wine Labs critic identifiers to filter results to specific critics.
top_score_per_critic	boolean	Optional	false	When true, returns one row per critic (their highest historical score for the resolved wine scope) with the corresponding review text.
limit	number	Optional	20	Page size (1–20).
offset	number	Optional	0	Pagination offset (>= 0).

Response Highlights

`lwin`: resolved LWIN echoed from the resolver.
`vintage`: applied vintage filter or null when broader results are returned.
`results[]`: critic review entries with scores, drinking windows, critic names, and source URLs.

At least one of `query`, `lwin`, or `wl_id` must be supplied.
Critic names must come from the documented allowlist; unknown names return a 400 error.

POST/wine_infoWine Info

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

Request Body

Field	Type	Required	Default	Description
user_id	string (UUID)	Required	None	Authorized user identifier used for authentication and rate limiting.
query	string	Optional	None	Free-text wine description. Required when `lwin` and `wl_id` are not provided.
lwin	string	Optional	None	Direct LWIN lookup. Required when `query` and `wl_id` are not provided.
wl_id	string	Optional	None	Wine Labs wine identifier. Required when `query` and `lwin` are not provided.
wine_label	boolean	Optional	false	Set to true to include a cleaned bottle image URL at `result.wine_label` when available.

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.wine_label`: cleaned bottle image URL when `wine_label` is true and a label is available.
`result.avg_beg_drink_window` / `result.avg_end_drink_window`: average critic drinking-window years for the resolved vintage, or null when no vintage/window is available.

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

Field	Type	Required	Default	Description
user_id	string (UUID)	Required	None	Authorized user identifier used for authentication and rate limiting.
query	string	Optional	None	Free-text product or wine description. Used with Wine Labs matching when provided.
lwin	string	Optional	None	Direct LWIN lookup for known wines.
wl_id	string	Optional	None	Wine Labs wine identifier for known wines.
vintage	string	Optional	None	Optional vintage used when enriching known wine attributes.
product_type / commodity_type / hs_code_6	string	Optional	None	Optional classification hints when the product is not supplied as a known wine.
container_size_ml, abv, color, origin_country, destination_country	number/string	Optional	None	Optional 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.

Imagery

Request cleaned bottle, front-label, and back-label assets, then track or export each delivery.

Wine Labels is part of a separate Imagery API tier. It does not use your Core, Markets, or Market Insights API quota.

Imagery uses delivery credits. A credit is used only when an asset is fulfilled; processing, unavailable, and failed requests do not use a credit.

POST/wine_labelsRequest Wine Imagery

Request one cleaned bottle image, front label, or back label for a wine. Ready assets are returned immediately; missing assets enter the processing queue.

Request Body

Field	Type	Required	Default	Description
user_id	string (UUID)	Optional	None	Account identifier. Optional when the request uses an authorized `Authorization` header.
query	string	Optional	None	Free-text wine name. At least one of `query`, `lwin`, or `wl_id` is required.
lwin	string	Optional	None	LWIN identifier. At least one of `query`, `lwin`, or `wl_id` is required.
wl_id	string	Optional	None	Wine Labs wine identifier. At least one of `query`, `lwin`, or `wl_id` is required.
vintage	string	Optional	None	Optional vintage. A four-digit year is required when `vintage_treatment` is `exact`.
label_type	string	Optional	bottle	Asset to deliver: `bottle`, `front_label`, or `back_label`.
vintage_treatment	string	Optional	exact	`exact` requires the requested year to be visible, `reusable` requires no visible vintage, and `any` accepts the best validated image.
vintage_specific	boolean	Optional	true	Legacy treatment selector used only when `vintage_treatment` is omitted. `true` maps to `exact`; `false` maps to `reusable`.
client_request_id	string	Optional	None	Optional caller-supplied identifier, up to 200 characters, for reconciling the request with your system.

Response Highlights

`request.status`: `fulfilled`, `processing`, `unavailable`, or `failed`.
`request.asset_url`: canonical download URL when fulfilled.
`request.status_url`: API route for refreshing this request.
`credits`: Imagery delivery credits included, used, and remaining.
`dashboard_url`: signed-in request dashboard at `https://winelabs.ai/api/imagery_requests`.

The canonical `asset_url` is a time-limited signed URL with a hash-only object path, for example `/winelabs/cleaned-labels/hash/bf3f78c66e58.png`.
Refresh an expired signed URL by listing requests or fetching the request again. Do not construct delivery URLs from wine names or slugs.
`asset_payload` preserves source and processing metadata; use `asset_url` for delivery.
A fulfilled request made with the live docs tester uses one Imagery delivery credit.

GET/wine_labelsList Imagery Requests

List imagery requests for the authorized account, with optional status filtering and pagination.

Query Parameters

Field	Type	Required	Default	Description
user_id	string (UUID)	Optional	None	Account identifier. Optional when the request uses an authorized `Authorization` header.
status	string	Optional	None	Filter by `processing`, `fulfilled`, `unavailable`, or `failed`.
limit	integer	Optional	50	Page size (1-100).
offset	integer	Optional	0	Pagination offset (>= 0).

Response Highlights

`requests[]`: request records in newest-first order.
`credits`: current Imagery delivery-credit balance.
`total`, `limit`, and `offset`: pagination metadata.

Fulfilled records return the canonical hash-only signed URL in `request.asset_url`.
Use the dashboard at `https://winelabs.ai/api/imagery_requests` to upload a CSV and review the same queue visually.

GET/wine_labels/exportExport Fulfilled Imagery

Download all fulfilled imagery requests for the authorized account as a CSV file.

Query Parameters

Field	Type	Required	Default	Description
user_id	string (UUID)	Optional	None	Account identifier. Optional when the request uses an authorized `Authorization` header.

Response Highlights

CSV columns: `wine_display_name`, `vintage`, `label_type`, and `download_url`.
`download_url`: canonical time-limited signed URL with a hash-only object path.
Only fulfilled requests with a delivered asset are included.

Call the export route again whenever signed download URLs need to be refreshed.

GET/wine_labels/{request_id}Get Imagery Request

Fetch the latest status and delivery URL for one imagery request owned by the authorized account.

Path Parameters

Field	Type	Required	Default	Description
request_id	string (UUID)	Required	None	Imagery request identifier returned by `POST /wine_labels`.

Query Parameters

Field	Type	Required	Default	Description
user_id	string (UUID)	Optional	None	Account identifier. Optional when the request uses an authorized `Authorization` header.

Response Highlights

`request`: current status, resolved wine identifiers, requested treatment, charge state, and timestamps.
`request.asset_url`: canonical hash-only signed download URL when fulfilled.
`credits`: current Imagery delivery-credit balance.

Returns 404 when the request does not exist or does not belong to the authorized account.

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

Field	Type	Required	Default	Description
query	string	Optional	None	Free-text wine description. Required when `lwin` is not provided.
lwin	string	Optional	None	Direct LWIN lookup. Required when `query` is not provided.
region	string	Optional	world	Target region alias. Supported values: world, europe, north america, south america, africa, asia, oceania.
currency	string	Optional	USD	Optional output currency (uppercased) used for price conversion.
user_id	string (UUID)	Required	None	Account 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).

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/listingsListings

Retrieve active merchant offers with optional geography and packaging filters.

Request Body

Field	Type	Required	Default	Description
query	string	Optional	None	Free-text wine description. Required when `lwin` is not provided.
lwin	string	Optional	None	Direct LWIN lookup. Required when `query` is not provided.
user_id	string (UUID)	Required	None	Account identifier issued during onboarding; used for authentication and quota tracking.
currency	string	Optional	USD	ISO currency code used for price conversion.
region	string	Optional	world	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	Optional	false	Filter to merchants designated as trusted partners.
continents	array<string>	Optional	[]	Restrict listings to the provided continents.
countries	array<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_formats	array<string>	Optional	[]	Filter by internal format labels (alias: `formats`). Allowed values: bottle, half-bottle, magnum, double-magnum.
vintages	array<string>	Optional	[]	Filter to specific vintages.
min_offer_volume	number	Optional	None	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	Optional	None	Maximum pack size filter (1–99). When absent and an 18-digit LWIN is provided, inferred from the LWIN case-size segment.
limit	number	Optional	20	Page size (1–20).
offset	number	Optional	0	Pagination 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 contact details, formats, and analytics flags.

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

Field	Type	Required	Default	Description
user_id	string (UUID)	Required	None	Authorized user identifier for pricing flows.
query	string	Optional	None	Free-text wine description; required when `lwin` is not provided.
lwin	string	Optional	None	Direct LWIN lookup; required when `query` is not provided.
vintage	string	Optional	None	Optional vintage to guide resolution and routing.
format	string	Optional	None	Bottle format hint used to route pricing logic.
condition	string	Optional	None	Bottle condition hint forwarded to the flow.
pack_size	number	Optional	None	Pack size (alias `packSize`) used for packaging adjustments.
currency	string	Optional	USD	Target currency for FX conversion; does not filter pricing sources.
flow_id	string	Optional	None	Specific 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

Field	Type	Required	Default	Description
user_id	string (UUID)	Required	None	Authorized user identifier used for authentication and rate limiting.
retailer_id	number	Optional	None	The retailer ID to look up. Required when not using search mode.
query	string	Optional	None	Search query for shop names (minimum 3 characters). When provided, activates search mode.
limit	number	Optional	10	Maximum results returned in search mode.
offset	number	Optional	0	Pagination 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_listingsRestaurant Listings

Find restaurant wine listings filtered by city, state, and/or coordinates, with optional distance sorting from a coordinate pair.

Request Body

Field	Type	Required	Default	Description
user_id	string (UUID)	Required	None	Authorized user identifier used for authentication and rate limiting.
city	string	Optional	None	City name used to match restaurant addresses (for example, `New York` or `Paris`). Required only when `state` and `lat`/`lng` are not provided.
state	string	Optional	None	Optional state filter for restaurant location. Accepts a 2-letter abbreviation or recognized full state name (for example, `CA` or `California`).
lat	number	Optional	None	Optional latitude of the search origin point. Must be provided together with `lng`.
lng	number	Optional	None	Optional longitude of the search origin point. Must be provided together with `lat`.
max_distance_miles	number	Optional	50	Maximum search radius in miles.
max_results	number	Optional	50	Maximum number of restaurant results to return.
vintage	array<string>	Optional	None	Optional vintage filter (e.g., ["2015", "2016"]).
format	array<string>	Optional	None	Optional bottle format filter (e.g., ["750ml", "1500ml"]).
country	array<string>	Optional	None	Optional country filter for restaurant location.
continent	array<string>	Optional	None	Optional continent filter for restaurant location.
currency	string	Optional	USD	Output currency for wine price conversion.

Response Highlights

`city`: echoed city filter when provided.
`state`: echoed normalized state filter when provided.
`lat`, `lng`: echoed search origin coordinates when provided.
`currency`: applied currency for prices.
`results[]`: array of restaurant listings, each containing:
`restaurant_id`, `restaurant_name`, `restaurant_address`: restaurant identification.
`restaurant_lat`, `restaurant_lng`: restaurant coordinates.
`distance_miles`: distance from search origin when coordinates are provided.
`wine_name`, `wine_vintage`, `wine_price`, `wine_format`: wine listing details.

Requires `markets` authorization. Uses the same rate limits as other market data endpoints.
Either `city`, `state`, or a full `lat`/`lng` pair is required.
`state` accepts 2-letter abbreviations or recognized full state names.
`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

Field	Type	Required	Default	Description
user_id	string (UUID)	Required	None	Authorized user identifier used for plan-based authentication and quota tracking.
auction_provider_ids	array<number>	Optional	[]	Filter results to specific auction providers.
query	string	Optional	None	Free-text wine description; optional when providing identifiers.
lwin	string	Optional	None	Direct LWIN filter.
vintage	string	Optional	None	Vintage filter.
lot_id	string	Optional	None	Internal Wine Labs lot identifier.
auction_lot_id	string	Optional	None	Provider-specific lot identifier.
auction_id	string \| number	Optional	None	Auction event identifier.
sold_date_from	date (YYYY-MM-DD)	Optional	None	Inclusive lower bound for sold date.
sold_date_to	date (YYYY-MM-DD)	Optional	None	Inclusive upper bound for sold date.
limit	number	Optional	10	Page size (1–100).
offset	number	Optional	0	Pagination offset (>= 0).
sort_by	string	Optional	sold_date	Sort options: sold_date, auction_date, hammer_price_usd, realised_price_usd, bottle_price_usd, auction_id.
sort_direction	string	Optional	desc	Sort 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 the supported auction-provider dataset with no provider-level conditions applied.
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

Field	Type	Required	Default	Description
user_id	string (UUID)	Required	None	Authorized user identifier used for plan-based authentication and quota tracking.
query	string	Optional	None	Free-text wine description; optional when identifiers are provided.
lwin	string	Optional	None	Direct LWIN filter.
vintage	string	Optional	None	Vintage filter.
sources	array<string>	Optional	[]	Restrict results to specific exchange sources.
bid_ask	string	Optional	None	Use "BID" or "ASK" to return only bids or asks.
format	string	Optional	None	Bottle format filter.
condition	string	Optional	None	Condition filter.
packaging	string	Optional	None	Packaging filter.
duty_code	string	Optional	None	Duty status filter (e.g., IB, DP).
currency_code	string	Optional	None	Optional target currency for FX conversion; does not filter order book rows by currency.
limit	number	Optional	10	Page size (1–100).
offset	number	Optional	0	Pagination offset (>= 0).
sort_by	string	Optional	price	Sort options: price, source, bid_ask, volume, currency_code.
sort_direction	string	Optional	asc	Sort 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`.
Exchange plan usage is split evenly across `/exchange/orderbook` and `/exchange/trades`.
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

Field	Type	Required	Default	Description
user_id	string (UUID)	Required	None	Authorized user identifier used for plan-based authentication and quota tracking.
query	string	Optional	None	Free-text wine description; optional when identifiers are provided.
lwin	string	Optional	None	Direct LWIN filter.
vintage	string	Optional	None	Vintage filter.
sources	array<string>	Optional	[]	Restrict results to specific exchange sources.
format	string	Optional	None	Bottle format filter.
condition	string	Optional	None	Condition filter.
packaging	string	Optional	None	Packaging filter.
duty_code	string	Optional	None	Duty status filter (e.g., IB, DP).
currency_code	string	Optional	None	Optional target currency for FX conversion; does not filter trades by currency.
traded_at_from	ISO 8601 datetime	Optional	None	Inclusive lower bound for trade timestamp.
traded_at_to	ISO 8601 datetime	Optional	None	Inclusive upper bound for trade timestamp.
limit	number	Optional	100	Page size (1–100).
offset	number	Optional	0	Pagination offset (>= 0).
sort_by	string	Optional	traded_at	Sort options: traded_at, price, source, volume.
sort_direction	string	Optional	desc	Sort 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`.
Exchange plan usage is split evenly across `/exchange/orderbook` and `/exchange/trades`.
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

Field	Type	Required	Default	Description
user_id	string (UUID)	Required	None	Authorized user identifier used for plan-based authentication and quota tracking.
auction_provider_ids	array<number>	Optional	[]	Optional auction-provider filter for transaction feeds that include auction venues.
query	string	Optional	None	Free-text wine description; optional when identifiers are provided.
lwin	string	Optional	None	Direct LWIN filter.
lwins	array<string>	Optional	[]	Batch list of LWIN values when requesting multiple wines in one call.
vintage	string	Optional	None	Vintage filter.
queries	array<string>	Optional	[]	Batch list of free-text wine queries when requesting multiple wines in one call.
sources	array<string>	Optional	[]	Restrict results to specific exchange sources.
format	string	Optional	None	Bottle format filter.
condition	string	Optional	None	Condition filter.
packaging	string	Optional	None	Packaging filter.
duty_code	string	Optional	None	Duty status filter (e.g., IB, DP).
currency_code	string	Optional	None	Optional target currency for FX conversion; does not filter trades by currency.
traded_at_from	ISO 8601 datetime	Optional	None	Inclusive lower bound for trade timestamp.
traded_at_to	ISO 8601 datetime	Optional	None	Inclusive upper bound for trade timestamp.
limit	number	Optional	100	Page size (1–100).
offset	number	Optional	0	Pagination offset (>= 0).
sort_by	string	Optional	traded_at	Sort options: traded_at, price, source, volume.
sort_direction	string	Optional	desc	Sort 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.
Exchange plan usage is split evenly across `/exchange/orderbook` and `/exchange/trades`; auction access is controlled by your auction subscription.
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.

POST/price_historyPrice History

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

Request Body

Field	Type	Required	Default	Description
query	string	Optional	None	Free-text wine description. Required when `lwin` is not provided.
lwin	string	Optional	None	Direct LWIN lookup. Required when `query` is not provided.
user_id	string (UUID)	Required	None	Authorized user identifier (accepts `user_id` or `userId`) required for market_insights access.
region	string	Optional	world	Region alias. Supported values: world, europe, north america, south america, africa, asia, oceania, uk, united kingdom, continental europe.
vintage	string	Optional	ALL	Vintage filter; use ALL to include every vintage.
currency	string	Optional	USD	Output currency (uppercased) for price conversion.
start_date	string (YYYY-MM-DD)	Optional	None	Inclusive start date filter; rejected when the format is invalid or if it is later than `end_date`.
end_date	string (YYYY-MM-DD)	Optional	None	Inclusive end date filter; validated against `start_date` and forwarded to the SQL query.
limit	number	Optional	10	Rows per page (clamped 1–100), ordered by newest date first.
offset	number	Optional	0	Pagination 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

Field	Type	Required	Default	Description
query	string	Optional	None	Free-text wine description. Required when `lwin` is not provided.
lwin	string	Optional	None	Direct LWIN lookup. Required when `query` is not provided.
userId	string (UUID)	Required	None	Authorized user identifier required for market_insights access.
region	string	Optional	world	Continent-level geography filter; overrides `continents` when provided. Supported values: world, europe, north america, south america, africa, asia, oceania.
currency	string	Optional	USD	Output currency (uppercased) for price conversion.
onlyTrustedMerchants	boolean	Optional	false	Filter results to trusted merchants only.
continents	array<string>	Optional	None	Geographic filter applied when `region` is not set.
countries	array<string>	Optional	None	Restrict 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.
formats	array<string>	Optional	None	Standardized format filters (e.g., bottle sizes).
vintages	array<string>	Optional	None	Filter to specific vintages.
changeTypes	array<string>	Optional	["removed"]	Types of changes to surface (e.g., removed, increased, decreased).
since	string	Optional	None	Lower bound timestamp for detected changes.
lastOnly	boolean	Optional	true	Return only the latest signal per location when true.
limit	number	Optional	10	Rows per page (clamped 1–10).
offset	number	Optional	0	Pagination offset (>= 0).
minPercentChange	number	Optional	3	Minimum 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.

POST/recent_critic_scoresRecent Critic Scores

Return the most recent critic reviews across wines with optional critic filters.

Request Body

Field	Type	Required	Default	Description
user_id	string (UUID)	Required	None	Authorized user identifier used for critic_scores access and rate limiting.
critic_wl_id	array<number>	Optional	[]	Optional list of Wine Labs critic IDs; defaults to all supported critics.
limit	number	Optional	20	Page size (1–100).
offset	number	Optional	0	Pagination offset (>= 0).

Response Highlights

`results[]`: recent critic reviews with critic metadata plus wine name, LWIN, and vintage.
`total`: total rows matching the filter.
`limit`, `offset`: pagination metadata echoed from the request.

Exclude or omit `critic_wl_id` to include all supported critics.

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

Field	Type	Required	Default	Description
user_id	string (UUID)	Required	None	Authorized user identifier for the custom feed dataset.
agg_level	string	Optional	vintage	Aggregation level; allowed values: vintage, format, volume.
currency	string	Optional	None	Optional target currency for FX conversion only; it does not filter the results.
page_limit	number	Optional	50 (max 500)	Rows per page; clamped between 1 and 500.
page_offset	number	Optional	0	Pagination offset (>= 0).
query	string	Optional	None	Free-text wine description used when resolving without `lwin`.
lwin	string	Optional	None	Direct LWIN filter; optional when `query` is provided.
wine_search	string	Optional	None	Search string applied to stored wine names.
sort_col	string	Optional	None	Optional sort column for the aggregation.
vintages	array<string>	Optional	None	Filter to specific vintages.
formats	array<number>	Optional	None	Filter to bottle formats by milliliter value.
volumes	array<number>	Optional	None	Filter 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

Field	Type	Required	Default	Description
user_id	string (UUID)	Required	None	Authorized user identifier for the custom feed dataset.
agg_level	string	Optional	vintage	Aggregation level; allowed values: vintage, format, volume.
currency	string	Optional	None	Optional target currency for FX conversion only; it does not filter the results.
page_limit	number	Optional	50 (max 500)	Rows per page; clamped between 1 and 500.
page_offset	number	Optional	0	Pagination offset (>= 0).
query	string	Optional	None	Free-text wine description used when resolving without `lwin`.
lwin	string	Optional	None	Direct LWIN filter; optional when `query` is provided.
wine_search	string	Optional	None	Search string applied to stored wine names.
sort_col	string	Optional	None	Optional sort column for the aggregation.
vintages	array<string>	Optional	None	Filter to specific vintages.
formats	array<number>	Optional	None	Filter to bottle formats by milliliter value.
volumes	array<number>	Optional	None	Filter 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

Field	Type	Required	Default	Description
user_id	string (UUID)	Required	None	Authorized user identifier for pricing flows.
query	string	Optional	None	Free-text wine description; required when `lwin` is not provided.
lwin	string	Optional	None	Direct LWIN lookup; required when `query` is not provided.
vintage	string	Optional	None	Optional vintage to guide resolution and routing.
format	string	Optional	None	Bottle format hint used to route pricing logic.
condition	string	Optional	None	Bottle condition hint forwarded to the flow.
pack_size	number	Optional	None	Pack size (alias `packSize`) used for packaging adjustments.
currency	string	Optional	USD	Target currency for FX conversion; does not filter pricing sources.
flow_id	string	Optional	None	Specific 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.