API conventions
Consistent conventions make your integration predictable across markets and endpoints.
Money is a decimal amount
Every price is a JSON number in the currency’s normal units, rounded to two decimal places: 30780.5 with currency: GBP is £30,780.50. A whole amount is written 600.0. Parse prices as decimals, not floats, if you do arithmetic on them.
Prices you send — a bid’s or an offer’s price, a listing’s cost — are the same: a number or a string such as "30780.50", more than zero, at most two decimal places, up to 100,000,000. The min_price and max_price filters take whole units: min_price=1200, never 1200.50.
Earlier drafts of this reference used integer minor units (60000 for £600.00). The API now sends and accepts decimal amounts everywhere.
Bids are net, offers are gross
A bid’s price in Cru’s book is what a seller receives for filling it, after Cru’s commission. An offer’s price is what a buyer pays. Your own bids show the gross price you offered; your listings show both: listing_price, your asking price, and net_proceeds, what comes to you, with Cru’s commission and any settlement_fee between them.
Which currency a price is in
Cru’s books, wine prices and market prices are in the currency of the market you call — each bid converted into it from the currency it was placed in, at today’s rate. So are your own bids, from the currency each was placed in, which bid_currency names, and your portfolio and listings, from the currency the wine was bought or listed in. Your purchases keep their order’s currency. Your sales are in the market’s: what you paid at the rate of the day you bought it, a sale of wine held outside Cru at the rate of the day it sold, and any other sale at the rate recorded with the unit. Every price arrives beside its currency; read it rather than assuming. Markets and currencies →
Wine identity stays together
A wine is identified by its lwin18: wine, vintage and pack in 18 digits. Match on all 18, not the 11-digit LWIN. wine_name, vintage and pack_size sit beside it on every object. A vintage of 1000 means non-vintage. Find an LWIN18 by name with GET /wines.
Pagination
Paged endpoints take limit and offset and return meta.pagination. A limit above the maximum is refused with VALIDATION_INVALID_VALUE, not reduced. The book can change between pages.
| ENDPOINT | DEFAULT · MAX | A PAGE COUNTS |
|---|---|---|
/market | 100 · 250 | Wines, each with its bids and offers |
/market/bids, /market/offers | 100 · 250 | Wines, each with all its bids or offers |
/bids, /trades/purchases, /trades/sales | 50 · 250 | Bids, order lines, units sold |
/offers | 50 · 250 | Wines, each with its listed portfolio lines |
/portfolio | 50 · 100 | Wines, each with its portfolio lines |
/wines | 25 · 50 | Wines. No total, and at most the 100 best matches |
Unknown parameters return an error
A misspelled or unsupported query parameter returns VALIDATION_UNKNOWN_PARAMETER / 400, and so does an unknown field in a write’s body. Nothing is silently ignored. An empty value, such as min_price=, counts as absent. Booleans are true or false (1 and 0 also work).
A comma-separated filter of fixed values, such as status or stock_type, takes each value once, in any case. More values than the filter has — live,LIVE counts as two — return VALIDATION_INVALID_VALUE before any is checked; a value it does not have returns VALIDATION_UNSUPPORTED_VALUE.
Dates and timestamps
Timestamps use RFC 3339 UTC, for example 2026-10-15T09:14:22Z. Date-only values use YYYY-MM-DD: fields ending _on, a market bid’s expires_at, a market offer’s eta and a sale’s deliver_by.
Identifiers are opaque
Codes are tokens: do not parse them or assume what is inside. Each kind has a fixed length, so a column of 80 characters holds any of them. Codes differ between environments.
BID-… | A bid, 47 characters. Your own bid has the same code in /market/bids and /bids. |
OFFER-… | An offer in Cru’s book, 49 characters. |
PORTFOLIO-… | One line of your portfolio, 74 characters. It changes when the line does, such as when it is repriced. A listed line’s is what /offers/{code} takes. |
LISTING-… | One of your listings, 72 characters. Only a connected app’s preview of a change gives one out, but /offers/{code} takes it for the whole listing. |
cnf_… | A confirmation code, 47 characters. A secret, valid for 15 minutes — treat it like a password. |
Trades have no id: a buy carries its Cru order number in reference.
Warehouses and condition
Warehouses are named by five codes: UK_DRAK, HK_KERRY, SG_TOLL, FR_DARTESS and US_NAPA. An offer in Cru’s book of wine held elsewhere names the Cru warehouse in the same country, so stock in Britain reads UK_DRAK; a third party’s warehouse is never named, and a country with no Cru warehouse is null. Their addresses →
Your own listings and portfolio lines say more, in one warehouse object. warehouse.current_location names where the wine is now, and warehouse.location_type what kind of place that is: cru, inbond, address or supplier — not to be confused with the line’s stock_type. warehouse.current_location_code is the code to filter on: a Cru warehouse’s code, IB_ and the inbond_address_id of an inbond warehouse outside Cru, such as IB_20, or ADDR_ and the id of your own address. warehouse.deliverable_warehouse_code is the Cru warehouse the wine can be delivered from, the code bids list as deliverable_warehouses: the one it is in or, for wine held outside Cru, the one it goes to once sold, which your own wine has only while it is listed. Inbond warehouses →
Every offer and every unit you hold has a condition_status, on an offer, a portfolio line and a purchased unit alike. The API sends and accepts the codes; Cru’s website, and this documentation, show the names. Beside it, condition_text is the written description of As per description and Client Reserve stock, and photo_urls are photos of the wine, when there are any. Strongest first:
| NAME · CODE | WHAT IT MEANS |
|---|---|
Verified · verified | Inventory that Cru World Wine, or one of its partners, has verified and found free of material faults. |
Client Reserve · client_reserves | Inventory a client transferred to Cru World Wine from another warehouse, not originally bought from Cru. It has no reported issues. |
As per description · apd | Inventory with a known issue, such as duty paid or damage to the case lid, which makes it non-fungible with no-fault inventory. |
Only Verified stock can be sold into a bid, so every bid’s requirements says verified. When you list wine held outside Cru, condition_status defaults to, and cannot exceed, the level Cru set for your account. A supplier’s own offer is verified unless you say otherwise, and duty-paid stock is always apd.
Resource ownership
/market is Cru’s read-only market: the bid and offer books. /bids, /offers, /portfolio and /trades/… are yours — the account the credential or token acts for.