Search wines
Find wines by name and get their LWIN18 codes, with producer, region, pack size, product page, Cru’s market price and the best bids and offers.
Every other endpoint identifies a wine by its LWIN18. This searches the way the Cru website does, best match first.
Query parameters
ONE REQUIRED| PARAMETER | DESCRIPTION |
|---|---|
| qstring · ≤ 100 chars · required | Words from the wine name, such as “Petrus Pomerol”: one to six words of two or more characters; one-letter words are left out. |
| vintageinteger · 1800–2100 | Only this vintage. |
| pack_sizestring | Only this pack, written as bottles x size: 12x75cl, 6x150cl. |
| limitinteger · 1–50 | Number of wines to return. A larger value is refused with VALIDATION_INVALID_VALUE, not reduced. Default: 25 |
| offsetinteger · ≥ 0 | Number of wines to skip. Default: 0 |
meta.pagination has has_more but no total, and the search considers its 100 best matches: paging past them finds nothing more. vintage and pack_size filter those 100 too, so narrow the words instead.
A credential that also holds market:read gets each wine’s best five bids and five offers, from the books rather than the search. With wines:read alone, the wine comes without those two keys.
Response fields
200 OKdata.wines, and data.currency — the currency of every price in them.
Each item in wines[]
lwin18string
The 18-digit LWIN: wine, vintage and pack together. Match on all 18 digits.
wine_namestring | null
Cru’s name for the wine.
vintageinteger | null
The vintage year. 1000 means non-vintage.
pack_sizestring | null
Pack format, for example 6x75cl.
producerstring | null
The producer.
regionstring | null
The region.
colourstring | null
Red, white, rosé and so on.
product_urlstring | null
The wine’s page on the Cru storefront for the market you called.
market_pricenumber | null
Always present: Cru’s market price in data.currency, or null when it has none.
bidsarray<object> · market:read
Up to five bids on the wine, as /market/bids lists them. An empty list when there are none. Absent without market:read.
offersarray<object> · market:read
Up to five offers, cheapest first, as /market/offers lists them. An empty list when there are none. Absent without market:read.
Each item in bids[]
codestring
Opaque bid code: BID- and 43 more characters. Do not parse it. Your own bids carry the same code here and in /bids.
pricenumber | null
Net price per unit — what a seller receives after Cru’s commission — converted into the market’s currency at today’s rate, to 2 decimal places. null in the rare case Cru cannot price the bid.
quantityinteger
Units the bid still wants.
is_own_bidboolean
True when the bid is yours. Your own bids are listed, but you cannot sell into one.
expires_atdate | null
YYYY-MM-DD. For bids Cru carries from other venues this is always set two days ahead, not taken from the venue.
updated_atdatetime | null
Last change, RFC 3339 UTC.
requirementsobject
What stock must satisfy to fill the bid: condition_status (always verified — only Verified stock can fill a bid), landed_stock_only, and deliverable_warehouses — the warehouse codes whose stock can fill it.
Each item in offers[]
codestring
Opaque offer code: OFFER- and 43 more characters. Do not parse it.
pricenumber
Gross price per unit — what a buyer pays — in the market’s currency.
quantityinteger
Units on offer at this price.
min_quantityinteger
The fewest units that can be bought from this offer — almost always 1. A smaller purchase is refused.
statusstring
in_stock, in_transit or due_in, as the Cru product page shows it. Offers from other sellers and venues are always due_in, except a customer’s own stock already in Cru storage, which is in_stock.
etadate | null
YYYY-MM-DD: when the wine is expected in warehouse_code, the warehouse it is sold from and where a purchase is kept. Today for in_stock. Null until Cru’s market index has dated the offer.
duty_paidboolean
Whether duty has been paid on the wine.
condition_statusstring | null
verified (Verified), client_reserves (Client Reserve) or apd (As per description), strongest first. API conventions explains each.
condition_textstring | null
The written condition of As per description and Client Reserve stock, or null. Liv-ex and supplier offers never have one.
photo_urlsarray<string>
Photos of the wine, [] when there are none. Cru’s own stock links to Cru’s media; other photos are served by GET /photos/{id}.
warehouse_codestring | null
The Cru warehouse the wine is in — UK_DRAK, HK_KERRY, SG_TOLL, FR_DARTESS, US_NAPA — or for wine held elsewhere the one in its country. Null where Cru has none there.
Errors
A request without q returns VALIDATION_REQUIRED_FIELD / 422. A q that is not one to six words of two or more characters or is over 100 characters, a vintage that is not a whole number from 1800 to 2100, a pack_size not written like 12x75cl, or a limit above 50, returns VALIDATION_INVALID_VALUE / 422. Missing or invalid credentials return AUTH_INVALID_CREDENTIALS / 401. A credential without wines:read gets AUTH_INSUFFICIENT_SCOPE / 403. View all error codes →