Conventions

Naming, types, dates, money, pagination.

Field naming

snake_case everywhere — both request body fields and response shapes.

Dates & timestamps

All timestamps are ISO 8601 with the source event’s original UTC offset preserved — never normalized to Z (UTC) or any single fixed zone.

• Korean auction events serialize as +09:00 (KST).
• Destination-side logistics events (e.g., Lagos customs arrival) serialize in the event’s local offset — +01:00 for WAT, etc.
• Bare UTC Z is not acceptable in partner-submitted fields — always include the actual offset of the event location.

Implementation note for Node.js consumers: Date.prototype.toISOString() always returns Z and is therefore not suitable. Use a serializer that preserves the offset (e.g., date-fns-tz, Luxon, or equivalent).

Money

• All amounts are USD integers (whole dollars, not cents).
• null for unset amounts (e.g., purchase_price_usd is null until the order reaches secured).
• Partner handles NGN (or other local currency) conversion; LMN does not surface non-USD prices.

IDs

Bare IDs (e.g., 01HXYZ...). No prefixes like ord_ or veh_. Order IDs are ULIDs (26 chars). Vehicle IDs follow the source’s native format.

Pagination

Cursor-based with composite (sort_field, id) cursors:

{
  "data": [ ... ],
  "next_cursor": "eyJ0cyI6IjIwMjYtMDQtMTVUMTA6MDAiLCJpZCI6IjAxSFhZWi4uLiJ9"
}

• next_cursor is null on the last page.
• Cursors are sort-specific — a cursor obtained with sort=X is invalid when the next request uses a different sort. Restart from page 1 if changing sort.
• Default page size is 50 (vehicles, orders); max 200. limit > max returns 400 validation_error.

Nullable fields

Always explicit null, never omitted. Clients should treat missing fields as schema bugs.

HTTP methods & status codes

Method	Usage
GET	Read-only resource fetch or list. Safe, idempotent.
POST	Create or trigger a state transition. POST /v1/orders requires Idempotency-Key; status pushes do not.
DELETE	Cancel an order. No Idempotency-Key required.

Operational boundary

┌─────────────────────────────────────────────────────────┐
│  LMN responsibility                                      │
│  • Inventory aggregation (auction + dealer)              │
│  • Cost estimation                                       │
│  • Bidding / direct purchase                             │
│  • Korean export (paperwork, port trucking, vessel load) │
└─────────────────────────────────────────────────────────┘
                         │   handoff at "vessel loaded"
┌────────────────────────┴────────────────────────────────┐
│  Partner responsibility                                  │
│  • Dealer identity, KYC, account management              │
│  • Ocean freight booking                                 │
│  • Destination customs clearance                         │
│  • Local delivery to dealer                              │
│  • Pushing post-shipped status back to LMN               │
└─────────────────────────────────────────────────────────┘

Versioning

/v1/ is the major-version prefix. Breaking changes increment to /v2/ with a 90-day deprecation window where both versions are served.

Every changelog entry identifies what changed:

Classification	Meaning
Breaking	Endpoint path/method removed, required request shape changed, response field removed/renamed, field type changed, or behavior requires client code changes.
Non-breaking additive	New optional response field, new endpoint, or new enum value on an existing field. Clients should ignore unknown fields and handle unknown enum values defensively.
Clarification	Docs/spec/examples corrected to match existing behavior. No wire behavior changed.
Operational	Testing, webhook setup, monitoring, or runbook guidance changed. No partner API payload changed.

When a version is marked “No request/response model shape changes”, it means no endpoint path, method, required request field, response object field, or field type changed.

Sandbox

Base URL: https://sandbox-api.lmnauto.com/v1/.

• Read endpoints return current auction inventory, using the same request/response contract as production.
• Orders are non-binding in sandbox and are safe for integration testing.
• Orders do not auto-advance. Use POST /v1/orders/{id}/sandbox-status to simulate lifecycle states and enqueue webhook events; coordinate with LMN ops when you want logs monitored during a test.
• Best-effort SLAs; no production guarantees.

SDK & OpenAPI

OpenAPI 3.1 spec available at GET /v1/openapi.json. Generate clients via openapi-generator or any compatible tool.