POST /v1/orders — Place order
This is a bid commitment, not a payment. No deposit. By POSTing, the partner takes commercial responsibility to pay LMN if (and only if) the order reaches secured. Money flow is described in Conventions.
curl -X POST \
-H "x-api-key: $KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"vehicle_id": "01HXYZ...", "max_bid_amount_usd": 15500}' \
https://api.lmnauto.com/v1/orders
| Header | Required | Description |
|---|
Idempotency-Key | Yes | UUID v4. Permanent uniqueness per (api_key, key). Replays return the original response. Reusing with a different vehicle_id returns 422 idempotency_key_reused. |
| Body field | Type | Required | Description |
|---|
vehicle_id | string | Yes | From GET /v1/vehicles. |
max_bid_amount_usd | integer | null | Conditional | Bid ceiling in whole USD. Required for auction vehicles (auction_result: "upcoming"). Must be > 0 and ≥ pricing.listing_usd. Null/omitted for buy-now (auction_result: "no_bid"). |
Response — 201 Created (or 200 OK on idempotent replay)
{
"id": "01HXYZ...",
"vehicle_id": "01HXYZ...",
"status": "proceed",
"max_bid_amount_usd": 15500,
"is_highest_bid": true,
"current_max_bid_usd": 15500,
"amounts": { "purchase_price_usd": null, "auction_fee_usd": null },
"auction_date": "2026-04-20T13:00:00+09:00",
"order_cutoff_at": "2026-04-19T00:00:00+09:00",
"created_at": "2026-04-11T10:00:00+09:00",
"updated_at": "2026-04-11T10:00:00+09:00"
}
Competitive bidding
Multiple partners may all order the same auction vehicle. All POSTs return 201. The response carries:
is_highest_bid (boolean) — whether your bid is currently the highest among all active orders.current_max_bid_usd (integer) — the highest active bid across all partners.
At auction time, LMN bids with the highest active max_bid_amount_usd. Winner gets secured; losers get failed (failure_reason: "outbid_internally").
Errors
| Code | HTTP | Condition |
|---|
missing_idempotency_key | 400 | Header absent. |
missing_max_bid | 400 | Auction vehicle, but max_bid_amount_usd null/omitted/below listing. |
vehicle_not_found | 404 | Unknown vehicle_id. |
past_order_cutoff | 409 | Past auction_date - 1 day, midnight KST. |
duplicate_order | 409 | Active order already exists for (your key, this vehicle). details.existing_order_id referenced. |
idempotency_key_reused | 422 | Same key, different vehicle_id. |
vehicle_unavailable | 410 | Listing disappeared before processing. |
GET /v1/orders — List
Paginated, filterable list of your orders. AND semantics across filters.
| Param | Description |
|---|
ids | CSV of order IDs (max 100). Foreign IDs silently dropped. Empty result → 200 with data: [] (not 404). |
status | Single status filter. |
from, to | ISO 8601 with offset. Half-open [from, to) on created_at. Both required if either present. |
sort | created_desc (default), created_asc, auction_date_asc, updated_desc. |
cursor, limit | Composite cursor (sort-specific); default 50, max 200. |
Sort use cases
| Value | When |
|---|
created_desc (default) | “Show what I just placed” |
created_asc | Backfill / oldest-first reconciliation |
auction_date_asc | ”Which of my orders resolves next?” Dealer-source orders (null auction_date) appear at the END (NULL LAST). |
updated_desc | ”What changed recently?” — useful when a webhook was missed |
Errors
| Code | HTTP | Condition |
|---|
validation_error | 400 | Bad enum, ids > 100, from without to, limit > 200. |
invalid_cursor | 400 | Cursor obtained with a different sort. Restart pagination. |
GET /v1/orders/ — Detail
Returns the full Order resource — current state, amounts, cutoffs, fulfillment_detail, shipment.
curl -H "x-api-key: $KEY" https://api.lmnauto.com/v1/orders/01HXYZ...
| Error | When |
|---|
404 order_not_found | Unknown ID, or order belongs to a different API key. |
is_highest_bid and current_max_bid_usd reflecting the latest competitive state.
Full Order schema in Schemas.
DELETE /v1/orders/ — Cancel
Allowed only when the order is in proceed status. Once LMN starts bidding (acquiring+), cancellation moves offline.
curl -X DELETE \
-H "x-api-key: $KEY" \
-H "Idempotency-Key: $(uuidgen)" \
https://api.lmnauto.com/v1/orders/01HXYZ...
200 OK with the updated Order (status: cancelled, cancellation_reason: dealer_cancelled).
No money flow has occurred pre-secured, so cancellation has no settlement implication. Partner-to-dealer arrangements are outside this API.
Race condition: If you DELETE while LMN concurrently transitions the order (e.g., proceed → acquiring), you may receive 409 invalid_status_transition. Re-fetch GET /v1/orders/{id} to see current state.
| Error | When |
|---|
missing_idempotency_key | 400 |
order_not_found | 404 |
invalid_status_transition | 409 — order not in proceed, or already cancelled. details.current_status shows actual state. |
