Writes & confirmations

Every write — placing, changing, cancelling or renewing a bid; listing, changing or removing an offer; buying an offer or selling into a bid; saving or removing an inbond address — runs one of two ways, and the credential alone decides which. A partner’s write executes at once. A connected app’s write is staged, and executes only when the app confirms it after the customer says yes.

What can be written

Over REST, POST /bids places a resting bid and POST /offers lists a line stored with Cru, wine held outside Cru or a supplier’s own stock, while POST /market/offers/{code}/buy buys an offer and POST /market/bids/{code}/sell sells into a bid straight away. The three inbond writes change no wine or money: they save or remove an inbond address, or suggest a warehouse, on your account. Suggesting needs warehouses:suggest, which Cru grants only to a partner credential, so a connected app never stages it.

The MCP tools follow the same rule: called with partner keys, each is carried out at once and takes a reference; with a connected app’s token, it stages, and confirm_instruction carries it out. With partner keys →

Partner credentials: at once, with a reference

The reference

Every write a partner credential sends must carry a reference in its JSON body — DELETE included. It is your idempotency key: Cru records the outcome against it, and any later request with the same reference gets that outcome back instead of being carried out.

What a repeat gets back

A refusal does not say which of the two it was. After one, send the corrected request with a new reference: that is right either way.

What a partner’s write returns

The message is Done; data.action names what ran, data.status is completed, and the rest is the result — the bid, the offer with the lines written, or what was removed. 201 for something new — a bid, a listing, a purchase, an inbond address or a suggested warehouse — and 200 for the rest.

{
  "status": "OK",
  "message": "Done",
  "meta": {
    "version": "1.0",
    "timestamp": "2026-10-19T10:10:55Z",
    "request_id": "6b183f2425c81699f1f3d3e5"
  },
  "data": {
    "action": "bid.place",
    "status": "completed",
    "bid": {
      "code": "BID-la4FCBHRAnKZ2vOaR8VF1KnHDYmFdaa_5N_mrFEFWzQ",
      "client_ref": "PO-2026-0193",
      "lwin18": "101187220240600750",
      "wine_name": "Lafite Rothschild 2024 (6x75cl)",
      "vintage": 2024,
      "pack_size": "6x75cl",
      "product_url": "https://markets.cruworldwine.com/uk/product/lafite-rothschild-2024-6x75cl",
      "price": 1650.5,
      "currency": "GBP",
      "bid_currency": "GBP",
      "quantity": 1,
      "quantity_matched": 0,
      "quantity_open": 1,
      "order_numbers": [],
      "order_urls": [],
      "status": "live",
      "renewable": false,
      "market": "uk",
      "local_only": false,
      "auto_transfer": false,
      "expires_on": "2027-01-17",
      "created_at": "2026-10-19T10:10:54Z",
      "updated_at": "2026-10-19T10:10:54Z"
    }
  }
}

Connected apps: staged, then confirmed

A write sent with a customer’s bearer token is checked against live data — the same validation and refusals a partner gets — and then stored with a preview. Nothing else happens until the app confirms it. The reference field is accepted and ignored.

{
  "status": "OK",
  "message": "Staged. Nothing happens until the confirmation code is confirmed",
  "meta": {
    "version": "1.0",
    "timestamp": "2026-10-19T10:10:55Z",
    "request_id": "6b183f2425c81699f1f3d3e5"
  },
  "data": {
    "confirmation": {
      "code": "cnf_5DT4rt0U-KyEjnQUzHPTGKw86dNTZ8uZud_zQFdTa-k",
      "action": "bid.place",
      "status": "pending",
      "expires_at": "2026-10-19T10:25:55Z",
      "preview": {
        "summary": "Bid GBP 1,650.50 per unit for 1 x Lafite Rothschild 2024 (6x75cl) - GBP 1,650.50 in total, live for 90 days. If a seller fills it, you pay the way any matched bid on Cru is paid: from your account credit first, then on invoice terms or by your saved card.",
        "lwin18": "101187220240600750",
        "wine_name": "Lafite Rothschild 2024 (6x75cl)",
        "quantity": 1,
        "price": 1650.5,
        "total": 1650.5,
        "currency": "GBP",
        "expires_on": "2027-01-17",
        "local_only": false,
        "auto_transfer": false,
        "client_ref": "PO-2026-0193",
        "allowance_remaining": 48349.5
      }
    }
  }
}

The preview is what the customer agrees to

preview.summary is one sentence a customer can say yes to: what, how many, at what price, the total, and anything that follows from it. Show it as it is. The rest of the preview is the same facts as fields, for your own display.

The rules a confirmation enforces

Before executing, Cru re-checks whatever may have moved since the preview. A bid changed elsewhere, an order that would now cost more, a bid that now pays less — each is refused with PRICE_CHANGED / 409, and anything Cru will no longer do with TRADE_REFUSED / 422, rather than doing something the customer did not see.

A confirmation’s life

GET shows a code’s state and preview, POST confirms it and DELETE discards it. A code staged through the MCP tools can be confirmed here too, by the same app, with a token issued for both.

How trades are paid

A bid that fills is paid from the customer’s Cru account credit first, then on invoice terms or by their saved card. Buying an offer is paid from account credit or on invoice only — never by card — and a connected app’s preview says which. Selling into a bid credits the proceeds to the customer’s Cru account.

Accounts that cannot trade

Cru refuses trades from accounts it has stopped from bidding, beyond their bidding allowance, or not set up to sell wine held outside Cru, with TRADE_REFUSED and a message saying which. An account on hold cannot place bids, buy or sell into a bid; its connected apps stop working altogether, with AUTH_ACCOUNT_ON_HOLD / 403.