Sell into a bid
Sell into one bid on Cru’s market now, at its price after commission, credited to your Cru account: a line of your portfolio, or new stock.
There is no “sell at the best bid”: pick one from GET /market/wines/{lwin18}/bids by its requirements. The sale needs offers:write besides orders:write. To buy an offer instead, POST /market/offers/{code}/buy.
How this write runs
offer.sell| Partner credentialCLIENT-KEY · CLIENT-SECRET | Executes at once and answers 200. The body must carry a reference: send the identical request again after a timeout and Cru replays the first outcome instead of acting twice. |
| Connected appAuthorization: Bearer | Answers 202 with a confirmation code and does nothing else. It runs only when the app calls POST /confirmations/{code} within 15 minutes, after the customer agrees. |
Writes & confirmations, in full →
Path parameter
REQUIRED| codestring | The bid’s opaque code, from GET /market/bids. URL-encode it as a single path segment. |
Request body
APPLICATION/JSON| FIELD | DESCRIPTION |
|---|---|
| referencestring · 1–50 chars · partners: required | Your idempotency key: letters and digits, then . _ : or - allowed. Required on a partner credential’s write and kept for good, so a retry with it can never act twice. Ignored for connected apps. |
| stock_typestring · required | What you are selling: cru, wine stored with Cru; external, wine you hold outside Cru; or supplier, your own stock as a supplier whose offer feed Cru imports. Anything else, bpo included, is refused with VALIDATION_INVALID_VALUE: BPO stock cannot be sold through the API. |
| portfolio_idstring · optional | A line of your portfolio, from GET /portfolio or GET /offers, of this bid’s wine and of the stock_type you send: its units are sold, and only those. Required for cru, as wine stored with Cru is always sold from your portfolio. Wine held outside Cru fills a bid only while its line is listed, as on the Cru website. Leave it out to sell new external or supplier stock. |
| quantityinteger · 1–1000 · required | Units to sell: with portfolio_id, at most what the line has that the bid can take. |
| min_pricenumber · > 0 · optional | The lowest price per unit you will take, after Cru’s commission, in the market’s currency — price as GET /market/bids shows it, less the settlement fee for wine held outside Cru — to at most 2 decimal places. |
| warehouse_codestring · external only · optional | New stock only, and needed for it: the Cru warehouse wine you hold outside Cru, not in your portfolio yet, is delivered to — one of the bid’s deliverable_warehouses that GET /warehouses marks sells_your_inbond_wine for you. |
| condition_statusstring · optional | New external or supplier stock only: verified, the one condition that can fill a bid, and the default. |
| costnumber · > 0 · external only · optional | New stock only: what you paid per unit, in the market’s currency. |
| inbond_address_idinteger · ≥ 1 · external only · optional | New stock only: the inbond warehouse the wine is in now, from GET /warehouses/inbond. Leave it out if you are not sure where the wine is: Cru records it as not sure, as the website’s Sell Now does. |
Any other field is refused with VALIDATION_UNKNOWN_PARAMETER / 400.
stock_type is now required, and Cru no longer picks which of your units fill the bid: send a line’s portfolio_id, which wine stored with Cru always needs, and only that line’s units are sold. warehouse_code no longer switches to selling new stock: stock_type external without a portfolio_id does. A listed line held outside Cru is now quoted as it is paid, less the settlement fee. New supplier stock can now be sold too: stock_type supplier without a portfolio_id. The answer, and a connected app’s preview, now carry stock_type and portfolio_id after bid_code.
A partner’s sale has no preview, so min_price is what holds the price you read from the book. If the bid pays less, nothing is sold.
For accounts Cru has set up to sell it, as the website’s Sell Now does: send stock_type external and warehouse_code, with no portfolio_id, and Cru creates the units — where your inbond_address_id says the wine is, or as not sure, due to go to that warehouse once sold — and fills the bid with them at once — or deletes them again, and sells nothing, if the fill fails. You set no price: you receive the bid’s price less that warehouse’s settlement fee — its settlement_fee in GET /warehouses, such as GBP 6.00 per unit at UK_DRAK — and a corporate account pays none. Selling confirms the wine is free from material faults, in its original packaging, in a professional warehouse and not duty paid, and that you will transfer it to that warehouse; Cru emails you the purchase order. A bid that takes landed stock only cannot be filled this way.
A supplier whose offer feed Cru imports can sell stock that is not in its feed: send stock_type supplier, with no portfolio_id. Cru adds an offer of just that quantity to your feed, at the feed’s warehouse, verified and not duty paid, and fills the bid with it at once, so selling it all leaves nothing on sale. If it cannot fill the bid, or the fill fails, it is taken back and nothing is sold. Supplier stock, new or a line of your portfolio, fills only bids placed on Cru.
Response fields
200 OK · 202 AcceptedWhat was sold, and from what. A connected app gets 202 and a confirmation whose preview quotes the sale.
Executed 200
actionstring
The action that ran, such as bid.place.
statusstring
completed.
soldinteger
Units sold: can be fewer than requested.
requestedinteger
The quantity you sent.
bid_codestring
The bid sold into.
stock_typestring
What was sold, as you sent it.
portfolio_idstring | null
The line sold from, as you sent it; null for new stock.
lwin18string
The wine.
pricenumber
Per unit, after commission, and after the settlement fee for wine held outside Cru.
totalnumber
Credited to your Cru account.
currencystring
The market’s currency.
Staged 202
confirmation.codestring
cnf_ and 43 more characters. A secret: the only handle on the instruction, valid for 15 minutes, once.
confirmation.actionstring
The action staged, such as bid.place.
confirmation.statusstring
pending.
confirmation.expires_atdatetime
RFC 3339 UTC.
confirmation.previewobject
summary, bid_code, stock_type, portfolio_id — null for new stock — lwin18, wine_name, quantity, price, total and currency; then for new external stock warehouse_code, condition_status, cost and inbond_address_id, or for new supplier stock condition_status.
Errors
A request without stock_type, or with stock_type cru and no portfolio_id, returns VALIDATION_REQUIRED_FIELD / 422. A stock_type other than cru, external or supplier; a portfolio_id that is not a line of your portfolio, or is a line of another wine or another stock_type; a field for new stock sent with a portfolio_id, or with a stock_type that does not take it; or a min_price that is not above 0 with at most 2 decimals returns VALIDATION_INVALID_VALUE / 422. A missing bid is BID_NOT_FOUND / 404. Your own bid, a bid no longer open, new stock of a wine Cru does not trade, or more than the line or the bid can take, is TRADE_REFUSED / 422, and so is a line that cannot fill the bid, with a message saying why: wine held outside Cru that is not listed, duty-paid or unverified stock, or stock that is not where the bid takes it from, has not landed when it must have, or is outside the bid’s market. A bid paying less than min_price — on staging too — or less than its preview is PRICE_CHANGED / 409. Without offers:write, AUTH_INSUFFICIENT_SCOPE / 403. New stock held outside Cru: external without warehouse_code is VALIDATION_REQUIRED_FIELD / 422; a warehouse that is not one of yours or not one the bid takes, a condition other than verified, or an inbond_address_id GET /warehouses/inbond does not list is VALIDATION_INVALID_VALUE / 422; and an account not set up for it, a bid taking landed stock only, wine held outside Cru that Cru has not set as verified, or a fill that fails is TRADE_REFUSED / 422. Supplier stock offered to a bid not placed on Cru, new supplier stock offered to a bid taking landed stock only, or new supplier stock from an account with no supplier offers on Cru, is TRADE_REFUSED / 422. Missing or invalid credentials return AUTH_INVALID_CREDENTIALS / 401. A credential without orders:write gets AUTH_INSUFFICIENT_SCOPE / 403. View all error codes →