Place a bid
Place a bid to buy a wine at your own price per unit. It rests on Cru for 90 days and fills when a seller accepts it.
This places a resting bid. To buy an offer straight away at its price, POST /market/offers/{code}/buy.
How this write runs
bid.place| 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 →
How this call works
4 STEPSYour server
Choose a reference and store it first
Generate the reference before sending, and keep it with your own record of the order. It is what makes the next step safe to repeat.
KEEP
referenceYour server
Send the bid
POST /bidsA partner credential’s write executes at once: 201 and the bid. A connected app gets 202 and a confirmation code instead.
KEEP
data.bid.codeCru
A repeat is replayed, never placed twice
After a timeout, send the identical request again. Cru returns the first outcome with Idempotent-Replayed: true, or 409 REQUEST_IN_PROGRESS while the first is still running.
Your server
Follow it until it fills
GET /bids/{code}Read it back with GET /bids/{code}, or by client_ref. quantity_matched rises as sellers fill it; GET /trades/purchases shows what you bought.
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. |
| lwin18string · 18 digits · required | The wine. Cru must trade it. |
| quantityinteger · 1–1000 · required | Units, in the LWIN18’s pack size. |
| pricenumber · > 0 · required | Gross price per unit you will pay, in the market’s currency, to at most 2 decimal places: 30780 or 30780.50. |
| local_onlyboolean · optional | Accept only stock already on this Cru site. Default false. |
| auto_transferboolean · optional | Move the wine into your storage on this site when the bid fills. Default false. |
| client_refstring · ≤ 50 chars · optional | Your own label for the bid — letters, digits, spaces and . / # : _ -, starting with a letter or digit — shown on it and filterable in GET /bids. Unique among all your bids, ignoring case. Not an idempotency key. |
Any other field is refused with VALIDATION_UNKNOWN_PARAMETER / 400.
price × quantity above the account’s allowance is refused with TRADE_REFUSED, and its message gives both amounts. So is an untraded wine, or an account that cannot bid.
Response fields
201 Created · 202 AcceptedA partner credential gets 201 and the bid it placed. A connected app gets 202 and data.confirmation: nothing has happened yet.
Executed 201
actionstring
The action that ran, such as bid.place.
statusstring
completed.
bidobject
The bid, as GET /bids/{code} returns it.
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, lwin18, wine_name, quantity, price, total, currency, expires_on (90 days on), local_only, auto_transfer, client_ref and allowance_remaining.
Errors
A client_ref already on one of your bids returns VALIDATION_INVALID_VALUE / 422, at confirmation too. Missing or invalid credentials return AUTH_INVALID_CREDENTIALS / 401. A credential without bids:write gets AUTH_INSUFFICIENT_SCOPE / 403. View all error codes →