List market offers
Explore Cru’s offer book: wines for sale on the market you call and their gross asking prices, cheapest first.
Offer prices are gross: what a buyer pays. The book covers the market you call, in its currency.
Query parameters
ALL OPTIONAL| PARAMETER | DESCRIPTION |
|---|---|
| limitinteger · 1–250 | Number of wines to return. A larger value is refused with VALIDATION_INVALID_VALUE, not reduced. Default: 100 |
| offsetinteger · ≥ 0 | Number of wines to skip. Default: 0 |
| lwinstring · CSV · ≤ 20 | Only these wines: up to 20 comma-separated LWIN18 codes. The books do not check the format, so a code that is not an LWIN18 simply matches nothing. |
| min_priceinteger · ≥ 0 | Lowest price to include, inclusive, in whole units of the market’s currency — 1200 is 1,200.00. Compared with the gross offer price. |
| max_priceinteger · ≥ 0 | Highest price to include, inclusive, in whole units of the market’s currency — 1200 is 1,200.00. Compared with the gross offer price. |
| depthinteger · ≥ 1 | How many offers to return per wine, cheapest first. Omit it for every offer. Default: every level |
| include_market_priceboolean | Add market_price — Cru’s market price for the wine, as a number — to each wine. Default: false |
| include_last_tradeboolean | Add last_trade — the last traded price and when — to each wine. Default: false |
limit, offset and total refer to wines, ordered by their cheapest offer. Each wine carries its offers, cheapest first.
The offer book, with each offer’s status and eta, is rebuilt by Cru’s market index rather than on every change, so it can trail the live market. Re-read an offer before acting on it.
Response fields
200 OK · pagedEach item in data.markets carries the wine and its nested offers.
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.
product_urlstring | null
The wine’s page on the Cru storefront for the market you called.
currencystring
ISO 4217 currency of every price in this market: the currency of the market you called.
market_pricenumber | null · optional
Only with include_market_price=true: Cru’s market price, in currency. Null when Cru has no price for the wine.
last_tradeobject | null · optional
Only with include_last_trade=true: price, and traded_at. Null when there is none.
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
An unknown query parameter returns VALIDATION_UNKNOWN_PARAMETER / 400. More than 20 lwin values return VALIDATION_INVALID_VALUE / 422. A limit, offset, depth, min_price or max_price that is not a whole number in range returns VALIDATION_INVALID_VALUE / 422, and a include_market_price or include_last_trade other than true or false VALIDATION_UNSUPPORTED_VALUE / 422. Missing or invalid credentials return AUTH_INVALID_CREDENTIALS / 401. A credential without market:read gets AUTH_INSUFFICIENT_SCOPE / 403. View all error codes →