List market bids
Explore Cru’s live bid book: what buyers will pay for each wine, net of commission, and the stock each bid accepts.
Bid prices are net of Cru’s commission: what a seller receives. Read the requirements on each bid to see which stock can fill it.
How this call works
4 STEPSYour server
Ask for one page of the book
GET /market/bidsFilter with lwin, wine_name, min_price and max_price to keep the page small, and deliverable_warehouse to see only the bids your stock could fill.
Cru
Cru returns wines, each with its bids
Prices are converted into the market’s currency and are net of commission — what a seller receives. Your own bids are included, marked is_own_bid.
KEEP
data.markets[].bids[].codeYour server
Page until has_more is false
meta.pagination counts wines, not bids. Advance offset by limit; do not assume the page you read is still current when you reach the end.
KEEP
meta.pagination.has_moreYour server
Re-read any bid before acting on it
GET /market/bids/{code}The book moves between calls. Take the code and retrieve that one bid to confirm its price and requirements as they are now.
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. |
| wine_namestring · ≤ 100 chars | Only wines whose name contains every word given, such as “Lafite 2010”. One to six words of two or more characters; one-letter words are left out. Anything else is refused with VALIDATION_INVALID_VALUE. |
| min_priceinteger · ≥ 0 | Lowest price to include, inclusive, in whole units of the market’s currency — 1200 is 1,200.00. Compared with each bid’s net price converted at the rate of the day it was placed, so near the limit a bid placed in another currency can fall either side of the price shown, which uses today’s. |
| max_priceinteger · ≥ 0 | Highest price to include, inclusive, in whole units of the market’s currency — 1200 is 1,200.00. Compared with each bid’s net price converted at the rate of the day it was placed, so near the limit a bid placed in another currency can fall either side of the price shown, which uses today’s. |
| depthinteger · ≥ 1 | How many bids to return per wine, in book order — bids placed on Cru first, newest first, then other venues’ bids by price, so depth=1 is not always the highest price. Omit it for every bid. Default: every level |
| landed_stock_onlyboolean | true for only bids that require stock that has already landed; false for only bids that do not. Omit it for both. Default: both |
| deliverable_warehousestring · CSV · ≤ 5 | Only bids that stock in any of these warehouses could fill: UK_DRAK, HK_KERRY, SG_TOLL, FR_DARTESS, US_NAPA. Case-insensitive. Pass a portfolio line’s warehouse.deliverable_warehouse_code to see the bids it can fill. Another code is refused with VALIDATION_INVALID_VALUE. |
| 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. Each wine carries every bid on it unless you set depth.
Wines with a bid placed on Cru come first, newest first, then by best bid. Within a wine, the bids placed on Cru lead, newest first, then other venues’ bids highest first — so depth=1 is not always the best price.
Response fields
200 OK · pagedEach item in data.markets carries the wine and its nested bids.
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 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.
Errors
An unknown query parameter returns VALIDATION_UNKNOWN_PARAMETER / 400. More than 20 lwin values, a wine_name that is not one to six words of two or more characters or is over 100 characters, or a deliverable_warehouse that is not a Cru warehouse code, or more than 5 of them, returns 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 landed_stock_only, 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 →