Buy an offer
Buy one offer on Cru’s market now, at its asking price, paid from your Cru account credit or on invoice and kept in your Cru storage.
There is no “buy at the lowest offer”: pick one from GET /market/wines/{lwin18}/offers. The purchase needs bids:write besides orders:write. To sell into a bid instead, POST /market/bids/{code}/sell.
How this write runs
bid.buy| Partner credentialCLIENT-KEY · CLIENT-SECRET | Executes at once and answers 201. 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 offer’s opaque code, from GET /market/offers. 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. |
| quantityinteger · 1–1000 · required | Units to buy: at least the offer’s min_quantity, and no more than it has. |
| max_pricenumber · > 0 · optional | The highest price per unit you will pay, in the market’s currency — price as GET /market/offers shows it — to at most 2 decimal places. |
Any other field is refused with VALIDATION_UNKNOWN_PARAMETER / 400.
A partner’s purchase has no preview, so max_price is what holds the price you read from the book. If the offer costs more, nothing is bought.
It goes through the Cru website’s own Buy now, paid from your Cru account credit, or on invoice if your account has invoice terms. The wine is kept in your Cru storage. If neither covers the total, nothing is bought, and the message gives your credit and the total.
Response fields
201 Created · 202 AcceptedThe order placed. A connected app gets 202 and a confirmation whose preview quotes the purchase and how it is paid.
Executed 201
actionstring
The action that ran, such as bid.place.
statusstring
completed.
orderobject
The Cru order: number, status, total, currency and pending_payment.
lwin18string
The wine.
quantityinteger
Units bought.
pricenumber
Per unit.
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, offer_code, lwin18, wine_name, quantity, price, total, currency and payment: account_credit or invoice.
Errors
A max_price that is not above 0 with at most 2 decimals returns VALIDATION_INVALID_VALUE / 422, and a missing offer OFFER_NOT_FOUND / 404. Fewer units than the offer’s min_quantity, more than it has, a total neither your account credit nor invoice terms cover, or a market whose bids are placed in a currency it does not quote in is TRADE_REFUSED / 422. An offer costing more than max_price — on staging too — or an order dearer than its preview is PRICE_CHANGED / 409. Without bids:write, AUTH_INSUFFICIENT_SCOPE / 403. Missing or invalid credentials return AUTH_INVALID_CREDENTIALS / 401. A credential without orders:write gets AUTH_INSUFFICIENT_SCOPE / 403. View all error codes →