Schemas

Vehicle, Order, Invoice, and shared Eagle Eye payload shapes.

Response display currency

Partner owners can choose USD (default), KRW or EUR in Partner Console → Settings. Preferences are separate for production and sandbox and apply across the partner’s API keys.

For API-key-authenticated vehicle, Eagle Eye, order and invoice JSON responses:

• Existing fields ending _usd or _krw retain their units and values.
• Existing pricing remains USD. New display_pricing has the same pricing structure, with monetary values converted to its currency; percentages and rates are unchanged.
• New suffix-free fields such as price, max_bid_amount and amounts.purchase_price use the adjacent currency. Where an existing field would collide (for example native purchase_price Money), converted values live in display_amounts instead.
• display_currency identifies the selected preference. display_fx.date identifies the daily rate snapshot; display_fx.usd_to_currency is selected-currency units per USD.
• KRW display amounts round to whole won; USD/EUR to two decimal places. Missing source amounts or unavailable FX produce null, never a fabricated rate. Zero remains zero.
• Display prices are estimates, not settlement instructions. Native Money objects, existing invoice currency/amounts, issued PDFs and order-locked exchange rates remain authoritative and unchanged. Invoice display_amounts are optional display estimates.
• Stored webhook payloads, event streams and request/filter units are unchanged.

Example: with EUR selected, a match can contain price_krw: 28000000, price: 18000 and currency: "EUR", while vehicle.pricing.listing_price remains 20000 USD and vehicle.display_pricing.listing_price is 18000 EUR. These are illustrative rates, not a live quote.

Vehicle

Two shapes — VehicleSummary (list view) and Vehicle (single fetch detail).

Eagle Eye reuses VehicleSummary for vehicles returned in search results, match rows, and eagle_eye.match webhook additions / price_changes. Eagle Eye-specific fields such as watch_id, match_reason, and signal_detail wrap this shared vehicle model.

VehicleSummary

Returned by GET /v1/vehicles.

Field	Type	Nullable	Notes
id	string	no	Vehicle ID. Two formats: auction listing/appearance ID with a source prefix (glovis_…, sk_…, aj_…, lotte_…, kcar_… — e.g., glovis_20260420_1064_2345), or dealer ID encar_<numeric>. Use this for GET /v1/vehicles/{id} and (auction only) POST /v1/orders. Auction IDs are not permanent physical-car IDs; the same car can receive a different ID when re-listed.
source	enum	no	dealer | glovis | sk | aj | lotte | kcar. dealer listings are fulfilled via a live proxy to a third-party retail inventory; see endpoint docs for dealer-specific constraints.
make	string	no
model	string	no
trim	string	yes	Dealer (encar_*) uses encar’s canonical English grade name.
year	integer	no
mileage_km	integer	no
fuel	enum	yes	gasoline | diesel | hybrid | electric | lpg | hydrogen | gasoline_hybrid | diesel_hybrid | plug_in_hybrid, or null for rare upstream gaps. Multi-word values use snake_case (e.g. gasoline_hybrid, never "gasoline hybrid") to match the options_include convention and avoid URL-encoding ambiguity. hydrogen covers Hyundai Nexo and similar FCEVs.
transmission	enum	yes	auto | manual | cvt | dct. Populated for dealer (encar_*) too as of 2026-06-03.
color	string	yes
engine_cc	integer	yes	Populated for dealer (encar_*) too as of 2026-06-03.
drivetrain	string	yes	e.g., FWD, AWD, 4WD.
options	array of strings	no	Equipment list. Empty array if none known. To filter by option, use the options_include query param — the full token catalog (62 dealer-filterable tokens + 2 dealer-unsupported) lives in Vehicles → options_include for dealer (full catalog).
accident_grade	enum	yes	A | B | C | D | F (no E). null for dealer source.
exterior_grade	enum	yes	A | B | C | D | F. null for dealer source.
auction_date	ISO 8601 with offset	yes	KST +09:00. null for dealer source.
order_cutoff_at	ISO 8601 with offset	yes	auction_date − N minutes, where N is your integration’s pre-negotiated lead time (default 1440 = 24h; lower for integrations without a secondary inspection step). null for dealer/buy-now. Updated 2026-04-29.
secondary_inspection_cutoff_at	ISO 8601 with offset	yes	Deadline for secondary_inspection_required: true orders: end of day (auction day − D) in your integration’s timezone (default D=2, Africa/Lagos — e.g. for a Thursday auction you have all of Tuesday, local time). Calendar-based — the auction’s start time is irrelevant. null for dealer/buy-now. Added 2026-07-08 (v1.48).
thumbnail_url	string (HTTPS URL)	yes
pricing	object	no	Summary shape: { listing_price, sold_price, discount_config, breakdown }. Monetary values are whole USD. As of 2026-05-26, discount_config and breakdown are returned on the summary too (same shape as detail) so list-view cards can show landed-cost without a per-row detail fetch. auction_fee_config, history, and market_assessment remain detail-only. See pricing.
auction_result	enum	yes	upcoming | sold | negotiation_sold | no_bid | negotiation_requested. null for dealer.
auction_count	integer	yes	Number of times listed at auction. null for dealer.
listing_status	enum	no	live | sold | reserved | ended. Availability of this record at serve time. live = currently offered; sold = concluded in a sale; reserved = under contract or awaiting completion; ended = an auction lot that ran without a recorded sale. Only GET /v1/vehicles/lookup/{key} returns records that are not live — browse and detail-by-id return 404 for those instead. When the value is not live, price and availability are historical and must not be quoted as an offer. Added 2026-09-10.

Vehicle (Detail)

VehicleSummary plus:

Field	Type	Nullable	Notes
vin	string	yes	Dealer (encar_*, added 2026-06-03): from the listing, or promoted from the inspection report’s 차대번호 when the listing omits it. null only when encar publishes no VIN for the listing (a minority — e.g. listings whose inspection is an abbreviated record with no structured form). Treat null as “not available from source” and request the VIN from the dealer where needed — do not infer it.
license_plate	string	yes	Korean format.
photos	array of HTTPS URLs	no	All photos (not just thumbnail).
photo_tags	array	no	Same photo URLs with a tag such as front, side_l, side_r, rear, interior, dashboard, front_seats, rear_seats, trunk, engine, odometer, vin, other. Each item is { url, tag }; array order follows photos. Most tags are positional heuristics from photo array order. vin is precision-tagged — when present, that photo shows the VIN plate (차대번호) and can appear at any index. At most one vin tag per car; vin may be absent when the upstream listing did not include a VIN plate photo or when one could not be identified with confidence.
body_condition	object	yes	{ image_url, panels[] } — panel-level damage map, for both auction and dealer sources. panels[] lists damaged panels only; a clean car returns { image_url, panels: [] } (an empty array, not null) so you still render the diagram. image_url is LMN-mirrored HTTPS media when available (Glovis), else null; upstream auction-site image URLs are not exposed. null only when the source has no inspection record.
inspection_report	object	yes	Source’s inspection, normalized to English-only keys for partner use. Populated for both auction and dealer sources whenever the inspection is reachable — a clean car returns a report with zero damage and a populated checklist[] (not null). Includes inspection_sheet_url (string | null — original inspection PDF; SK/AJ only, else null). Dealer (encar_*) reports carry a dealer_inspection block ({ critical_frame_damage, exterior_damage, rank_counts, frame_status, panel_status, simple_repair, insurance_history, insurance_amount, vehicle_info, overall_status[], photos[], certification, registration_no }; rank_counts is { rank_one, rank_two, rank_a, rank_b, rank_c } — integer per-rank damaged-panel counts, where rank_a + rank_b + rank_c === critical_frame_damage and rank_one + rank_two === exterior_damage; vehicle_info holds only inspection-form-specific fields — Valid Period, Warranty, Engine Model, etc. — identity like make/model/year/plate/VIN is top-level only) and surface accident state via has_accident / accident_summary rather than accident_history[]. null only when the source has no inspection record (e.g. dealer upstream 404) or the fetch failed transiently. Retains category_grades[] and issues[] for backward compatibility (auction-rich; dealer emits category_grades as frame/exterior and an empty issues[]). Any monetary fields in accident_cost_summary, and dealer_inspection.insurance_amount, are whole USD (FX-converted server-side).
comparables	object	no	{ past_sales, upcoming_sales }. Each comparable includes vehicle_id, vin, license_plate, USD price fields, and auction metadata. upcoming_sales does not include sold_price.
pricing	object	no	Adds fee config, landed-cost breakdown, same-car history, and market assessment. See pricing.
order	object	yes	Your order on this car, when the response was served from that order’s snapshot: { id, status, purchase_price, purchase_price_usd, buyable }. Present on every detail response — null unless you hold an order with a vehicle snapshot on this car and the detail came from that snapshot (an active or delivered order via GET /v1/vehicles/{id}; any Encar (encar_*) order via GET /v1/orders/{id}/vehicle). null for every other caller and for every auction (glovis_* …) and Danawa vehicle. When non-null, buyable is always false and pricing.listing_price is your recorded purchase price where one exists. See order. Added 2026-09 (v1.61).

pricing

pricing groups this vehicle’s prices, fee estimates, same-car history, and market assessment. Every monetary number inside this object is a whole USD integer.

Field	Type	Nullable	Notes
listing_price	integer	no	Current listed/estimated vehicle price. For auction vehicles this is the estimated final price when comparable-market data exists, otherwise the auction starting price. For dealer vehicles this is the asking price. Ordering-partner override: when you hold an order on this car with a recorded purchase price and the detail is served from your order snapshot (order non-null), this is that purchase price in whole USD instead, and discount_config.vehicle_discount_pct / fixed_discount_amount are 0. Summary + detail.
sold_price	integer	yes	Final sold price when the auction result is sold or negotiation_sold; otherwise null. Summary + detail.
discount_config	object	no	{ bid_threshold, rate_below, rate_at_or_above, fixed_discount_amount, vehicle_discount_pct }. Always populated. For auction: bid-based fields drive the discount, fixed_discount_amount is 0. For dealer: bid-based fields are all 0; fixed_discount_amount carries the entire economic effect (300 USD, offsets the flat dealer fee). bid_threshold is compared against the partner’s bid amount, not the listing price. vehicle_discount_pct is a whole-percent integer; partner-specific — 0 for partners without a configured discount. When vehicle_discount_pct > 0, the basis is discounted before fees/freight/LMN are added, and the bid-rate fields (bid_threshold, rate_below, rate_at_or_above) and dealer fixed_discount_amount are all 0 (the vehicle discount replaces them entirely). Summary + detail (added to summary 2026-05-26).
breakdown	object	no	Illustrative landed-cost estimate. Contains auction_fee, dealer_fee, lmn_commission, ocean_freight, and estimated_landed. ocean_freight varies per vehicle by body type and maker — it is not a fixed value: Mercedes-Benz is 1800 (any body type); other makers are 1800 for SUV-class (SUV, minivan, van, truck) and 1500 for sedan-class (sedan, compact, wagon, coupe, convertible); vehicles with an unknown body type use 1500. Read the value from each response rather than hardcoding it. Fee shape is symmetric — both auction_fee and dealer_fee are always integers (0 where the concept doesn’t apply, real value where it does); branch on source, not on null. For auction: auction_fee populated, dealer_fee: 0. For dealer: auction_fee: 0, dealer_fee: 300 (flat USD). estimated_landed for auction: basis + auction_fee + lmn_commission + ocean_freight − (bid_rate_discount + fixed_discount_amount). For dealer: listing_price + dealer_fee + lmn_commission + ocean_freight − fixed_discount_amount (dealer_fee and fixed_discount net to zero, so this reduces to listing_price + lmn_commission + ocean_freight). For exact auction totals at the partner’s own bid, recompute using auction_fee_config and discount_config. For an ordered car served with a recorded purchase price (order.purchase_price_usd set), estimated_landed is re-derived as that purchase price plus the frozen auction_fee + dealer_fee + lmn_commission + ocean_freight (no discount term), or null when the frozen order-time estimate can’t be trusted. Summary + detail (added to summary 2026-05-26).
auction_fee_config	object	yes	{ percentage, minimum, maximum }, where minimum and maximum are source/category fee caps converted to USD. null for dealer. Detail only — fee schedule is constant per source/category so partners can hold a static copy.
history	array	no	Same physical vehicle’s auction appearances, not comparable cars.
market_assessment	object	yes	Server-side price verdict over sold comps; null for dealer.

order (ordered vehicle)

Present on every VehicleDetail served by the vehicle endpoints (the one exception is the frozen vehicle blob embedded on the Order resource — see Order). Non-null only when you hold an order with a vehicle snapshot on this car and the response was served from that snapshot — an active or delivered order via GET /v1/vehicles/{id}, or any Encar (encar_*) order (including failed / cancelled) via GET /v1/orders/{id}/vehicle. null for every other caller and path, including every auction and Danawa vehicle.

Field	Type	Nullable	Notes
id	string (ULID)	no	The order’s id; use with GET /v1/orders/{id}.
status	enum	no	Same values as Order.status (see the state machine under Order).
purchase_price	object	yes	{ amount, currency } — the recorded purchase price in its native currency (KRW or USD). null until a purchase price is recorded, or on a legacy order that carries only a USD amount.
purchase_price_usd	integer	yes	Whole USD. Stored, else derived, else null: the order’s stored USD amount when present; otherwise derived from purchase_price (rounded half-up to a whole dollar for USD, converted at the order’s locked fx_rate for KRW); null when neither is available. Equals Order.amounts.purchase_price_usd only in the stored case.
buyable	boolean	no	Always false when order is non-null. An order snapshot is a historical view and never establishes current availability — the car may be sold or under contract, or you may already hold a newer active order on it.

When purchase_price_usd is set, pricing on the same response is overridden (unless the stored snapshot has no pricing at all — rare, legacy rows — in which case pricing is returned as stored and only order carries the price): pricing.listing_price is that USD figure, pricing.discount_config.vehicle_discount_pct and fixed_discount_amount are 0 (the purchase price is the negotiated final; no partner discount is applied on top), and pricing.breakdown.estimated_landed is re-derived from it. When no USD figure exists, pricing is the untouched order-time snapshot. pricing.history and pricing.market_assessment pass through unchanged either way.

Worked example — a placed dealer order with a recorded purchase price of ₩34,170,000 at the order’s locked fx_rate (fee components are passed through exactly as frozen at order creation; this partner’s dealer fee is folded into the purchase price, hence dealer_fee: 0):

{
  "id": "encar_42183520",
  "source": "dealer",
  "pricing": {
    "listing_price": 25386,
    "sold_price": null,
    "discount_config": { "bid_threshold": 0, "rate_below": 0, "rate_at_or_above": 0, "fixed_discount_amount": 0, "vehicle_discount_pct": 0 },
    "breakdown": { "auction_fee": 0, "dealer_fee": 0, "lmn_commission": 300, "ocean_freight": 2000, "estimated_landed": 27686 }
  },
  "order": {
    "id": "01M1Y9SSACQJB2S7YWMZ9NYXQV",
    "status": "placed",
    "purchase_price": { "amount": 34170000, "currency": "KRW" },
    "purchase_price_usd": 25386,
    "buyable": false
  }
}

How to render: hide Buy whenever order is non-null (equivalently order.buyable === false — the two never disagree) and show the order status instead. Show pricing.listing_price as the vehicle price; it already reflects your purchase price when one is recorded. After a failed or cancelled order, call GET /v1/vehicles/{id} for live availability — it answers from live inventory (the current listing, or 404 if the car is gone) with order: null.

Order

Returned by POST /v1/orders, GET /v1/orders, GET /v1/orders/{id}, DELETE /v1/orders/{id}, POST /v1/orders/{id}/status.

Use GET /v1/orders/{id}/vehicle for the purchased vehicle snapshot. That response is the same VehicleDetail schema as GET /v1/vehicles/{id} and is stored at order creation so dealer purchases remain readable after the live Encar listing is removed. That response also carries order — always non-null there, with buyable: false, keyed to the order you asked for (including failed / cancelled orders) when the order is for an Encar (encar_*) vehicle; auction and Danawa order snapshots come back with order: null and their pricing untouched — and applies the same purchase-price override to pricing.listing_price that GET /v1/vehicles/{id} applies for the ordering partner.

One exception to “every VehicleDetail carries order”: the vehicle object embedded on the Order resource itself (GET /v1/orders/{id}, order webhooks) is the frozen snapshot returned verbatim. It is not overlaid — its pricing.listing_price stays the order-time listing, and order is absent on orders created before v1.61 and null afterwards. Read the purchase price from amounts.purchase_price_usd on the order, or fetch GET /v1/orders/{id}/vehicle for the overlaid detail.

Field	Type	Nullable	Notes
id	string (ULID)	no
vehicle_id	string	no	Auction listing/appearance ID the order was placed against. Not a permanent physical-car ID.
vin	string	yes	VIN snapshotted from the upstream listing at order creation. null when the upstream listing carried no VIN. Self-contained — webhook consumers can match dealer records without a follow-up GET /v1/vehicles/{id}.
license_plate	string	yes	Korean license plate snapshotted at order creation. null when the upstream listing carried no plate.
options	array of strings	no	English Title-case feature names (e.g. Sunroof, Leather Seats, LED Headlamps) snapshotted from the vehicle at order creation. Byte-equal to Vehicle.options on GET /v1/vehicles/{id} so consumers don’t need a follow-up lookup. Both auction and dealer (encar_*) sources return Title-case English. Empty array ([]) when the upstream listing exposed no options, or for orders created before v1.21.
status	enum	no	See state machine below.
max_bid_amount_usd	integer	yes	Whole USD. Set at creation. null for buy-now/dealer. Settlement obligation applies only on secured.
is_highest_bid	boolean	no	Computed; true when no competing orders.
current_max_bid_usd	integer	no	Computed across all active orders for the vehicle.
amounts	object	no	{ purchase_price_usd, auction_fee_usd } — whole USD. purchase_price_usd is null until a purchase price is recorded (normally at secured, but LMN ops may record it earlier — e.g. a negotiated dealer price on a placed order); auction_fee_usd is null until secured. Computed from the KRW price using the order’s locked fx_rate.
invoice	object	yes	Summary of the order’s newest invoice — { id, number, version, status, currency, total, issued_at, document_url }. null when the order has no invoice; a draft appears as soon as the order is secured with status: draft, number: null, document_url: null. Identical on GET /v1/orders/{id} and on data.order of every order.* webhook. See OrderInvoiceSummary and Invoices. Added 2026-09 (v1.60).
fx_rate	number	yes	KRW-per-USD rate locked at order creation time. Does not change on PATCH or status updates — the settlement amount is deterministic from day one. null only if the FX provider was unavailable when the order was created; in that case LMN applies the secured-day rate (communicated offline).
auction_date	ISO 8601	yes	null for dealer orders.
order_cutoff_at	ISO 8601	yes	null for dealer/buy-now.
secondary_inspection_cutoff_at	ISO 8601	yes	The inspection request cutoff enforced at creation. null unless the order was created with secondary_inspection_required: true on an auction vehicle (also null for orders predating v1.48).
secondary_inspection_url	string (URL)	yes	LMN URL of the completed secondary-inspection report. Populated when the order reaches secondary_inspection_ready (when available) — the order.status_changed webhook for that transition carries it, so you can surface the report at the confirm/decline decision point. null before the inspection completes and for orders without a recorded report. Added 2026-07-15 (v1.49).
acquired_at	ISO 8601	yes	Set at secured.
shipped_at	ISO 8601	yes	Set at in_transit.
shipment	object	yes	null until export_processing. See below.
failure_reason	enum	yes	Set only when status: failed. Mutually exclusive with cancellation_reason.
cancellation_reason	enum	yes	Set only when status: cancelled. Mutually exclusive with failure_reason.
created_at	ISO 8601	no
updated_at	ISO 8601	no

shipment object

null until in_transit; populated by LMN at vessel loading. Stable for the rest of the shipping leg.

Field	Type	Notes
vessel_name	string	e.g., Glovis Sky.
voyage	string	e.g., GS-2604E.
bl_number	string	Bill of Lading number from the carrier, e.g., MAEU1234567890. Carrier-specific format; free-form alphanumeric. Use as the correlation key when filing customs entries or raising disputes — every party sees the same value.
container_id	string	Container holding the vehicle, e.g., MSKU7654321. Typically follows ISO 6346 (4 letters + 6 digits + 1 check digit); format is not enforced at the API layer.
etd_korea	ISO 8601	Departure from Korean port.
eta_destination	ISO 8601	Estimated arrival at destination port.
destination_port	string	e.g., Tin Can Island, Lagos.

Order status enum (11 values)

placed ─┬─→ acquiring → secured → export_processing → in_transit → customs → delivered
        │      └─→ failed                                (acquiring only)
        ├─→ secondary_inspection_in_progress → secondary_inspection_ready ─┬─→ acquiring
        │                                              └─→ cancelled (secondary_inspection_declined / secondary_inspection_failed)
        └─→ cancelled                                  (from placed)

Inspection is optional: an order may go placed → acquiring directly (skip inspection) or placed → secondary_inspection_in_progress → secondary_inspection_ready → acquiring (inspected). When inspection fails, the order is cancelled (reason secondary_inspection_failed), never failed.

Value	Set by	Meaning	Terminal
placed	Partner	Order accepted; LMN has queued it.
secondary_inspection_in_progress	LMN	Optional pre-acquisition inspection underway. On complete → secondary_inspection_ready.
secondary_inspection_ready	LMN	Inspection completed. Partner may confirm (POST /v1/orders/{id}/confirm → acquiring) or decline (DELETE /v1/orders/{id} → cancelled, reason secondary_inspection_declined); LMN/admin may also advance to acquiring or cancel (reason secondary_inspection_failed).
acquiring	LMN	LMN is bidding (auction) or purchasing (dealer).
secured	LMN	Vehicle won/purchased; purchase_price and auction_fee_usd locked.
export_processing	LMN	Title transferred to LMN; Korean export workflow in progress (declaration, port trucking, vessel booking, loading).
in_transit	LMN	Bill of Lading issued and vessel has departed Korean port.
customs	Partner	Vessel arrived at destination port; vehicle in customs-bonded area.
delivered	Partner	Customs cleared and vehicle handed to the dealer. Partner must push this — terminal.	✅
failed	LMN	Acquisition did not complete (failure_reason set). Reachable from acquiring only.	✅
cancelled	Partner or LMN	Reachable from placed (Partner via DELETE, or LMN auto-cancel: reschedule-too-soon, source-cancel, seller-withdraw) or from secondary_inspection_ready (Partner via DELETE, reason secondary_inspection_declined; or LMN/admin, reason secondary_inspection_failed).	✅

Boundary: statuses up to in_transit are LMN-driven (server-side). From customs onward, the partner pushes via POST /v1/orders/{id}/status.

failure_reason enum

Value	When	Triggers from
outbid	External bidder exceeded the partner’s max bid at auction.	acquiring
outbid_internally	Another partner’s higher bid won at auction. All competing placed orders on the same lot enter acquiring together before resolution.	acquiring
vehicle_unavailable	LMN’s dealer purchase attempt fails because the car was sold to another buyer.	acquiring
auction_cancelled	Auction house cancels the event after LMN has begun bidding. Pre-acquiring discovery routes to cancelled (see cancellation_reason).	acquiring
auction_passed	Vehicle was passed at auction (no winning bid), OR system zombie cleanup at auction_date + 24h for orders LMN never picked up.	acquiring
seller_withdrew	Seller withdrew the car after LMN started attempting to acquire. Pre-acquiring discovery routes to cancelled (see cancellation_reason).	acquiring

cancellation_reason enum

Value	When	Triggers from
dealer_cancelled	Partner sent DELETE /v1/orders/{id} while placed.	placed
secondary_inspection_declined	Partner sent DELETE /v1/orders/{id} while secondary_inspection_ready.	secondary_inspection_ready
secondary_inspection_failed	Admin judged the inspection disqualifying and cancelled while secondary_inspection_ready.	secondary_inspection_ready
auction_rescheduled_too_soon	LMN auto-cancel because the auction was rescheduled past the order cutoff.	placed
auction_cancelled	LMN auto-cancel because the auction event was cancelled before LMN started bidding.	placed
seller_withdrew	LMN auto-cancel because the seller pulled the dealer listing before LMN started purchase.	placed

failure_reason and cancellation_reason are mutually exclusive — an order has one or the other, never both. For reasons that appear in both enums (auction_cancelled, seller_withdrew), the order’s current status at the moment of the upstream event decides which terminal — and therefore which field — applies.

Settlement

At secured: partner owes LMN purchase_price_usd + auction_fee_usd + lmn_commission_usd + ocean_freight_usd − discount_usd, where discount = ceil(purchase_price_usd × rate / 100) + fixed_discount_amount; rate follows pricing.discount_config evaluated against purchase_price_usd (the actual hammer price). The amount due is the invoice LMN issues for the order — read it via GET /v1/orders/{id}/invoice or GET /v1/invoices, and download the PDF from GET /v1/invoices/{invoice_id}/document (see Invoices). The invoice carries a single bundled price; the cost components above are not itemised on the API or the PDF. The invoice is authoritative. Wire transfer same US business day expected.

There is no dealer-deposit concept in this API. Partner-to-dealer arrangements are entirely outside LMN’s scope.

Invoice

Returned by GET /v1/invoices, GET /v1/invoices/{invoice_id}, and GET /v1/orders/{id}/invoice; carried in full on the order.invoice_issued webhook. Lifecycle, number format, and usage in Invoices.

One live (non-void) invoice per order. LMN drafts it automatically when the order reaches secured and issues it from the LMN admin. Amounts are numbers in major units with at most 2 decimals (unlike the whole-USD integers on Order.amounts). Timestamps keep the +09:00 offset.

Field	Type	Nullable	Notes
id	string (ULID)	no
number	string	yes	{prefix}_{YYYY}_{MM}_{seq} — e.g. SKL_2026_09_001. Assigned at first issue, unchanged by re-issues; null while status: draft.
version	integer	no	Published document version: 0 while draft, 1 on first issue, +1 per re-issue. Each version keeps its own PDF.
status	enum	no	draft | issued | paid | void. See status.
order_id	string (ULID)	no
dealer_id	string	yes	Your dealer id as supplied on the order. null for orders LMN created offline on your behalf.
vehicle	object	no	{ vehicle_id, vin, license_plate, make, model, year, fuel_type, cc, weight_kg }. Copied from the order; cc / weight_kg are typed by LMN ops for the packing list (null until entered). Every field except vehicle_id is nullable.
consignee	object	yes	{ name, address, email, phone, company_registration } — your dealer as printed on the PDF, typed by LMN ops (pre-filled from the dealer’s previous invoice). null on a draft with no consignee yet; name and address are always present once issued, the rest nullable.
currency	string	no	ISO 4217. USD at launch.
amounts	object	no	{ price, ocean_freight, insurance, total }. See below.
terms	object	no	{ payment, incoterm, port, country_of_origin } as printed on the PDF — e.g. 100% in advance by T/T, CFR, Incheon, Korea.
shipment_month	string	yes	YYYY-MM the number is sequenced under. null on a draft until LMN ops sets it; immutable once the number is assigned.
packing	object	no	{ terminal_name, terminal_code, container_no, loaded_by, departure_note } — packing-list block, every field nullable. Typically completed on a re-issue once the container is loaded.
document_url	string (URL)	yes	GET /v1/invoices/{invoice_id}/document?version=N for this resource’s version — always pinned. null while draft.
issued_at	ISO 8601	yes	First publication. null while draft; unchanged by re-issues.
paid_at	ISO 8601	yes	null unless status: paid.
voided_at	ISO 8601	yes	null unless status: void.
void_reason	string	yes	null unless status: void.
created_at	ISO 8601	no	Draft creation.
updated_at	ISO 8601	no

Invoice amounts object

Field	Type	Nullable	Notes
price	number	yes	Bundled vehicle price — one figure. LMN’s cost components (commission, discount) are not itemised on the API or the PDF. null on a draft whose price cannot be resolved yet.
ocean_freight	number	yes	Ocean freight when LMN lists it as a separate line; null when freight is included in price. Never both.
insurance	number	yes	Additional insurance line; null when none.
total	number	yes	price + ocean_freight + insurance (null lines count as 0). null while price is null.

While status: draft, amounts are recomputed from the order on every read and may change between reads. They are frozen at issue.

Invoice status enum

draft → issued → paid
  └───────┴────────┴──→ void

Value	Set by	Meaning	Webhook	Terminal
draft	LMN (auto)	Created when the order reaches secured; visible on the API immediately; no number, no PDF.	—
issued	LMN ops	Number assigned, PDF published. A re-issue keeps the status (issued or paid), bumps version, publishes a new PDF, and fires the webhook again with previous_version.	✅ order.invoice_issued
paid	LMN ops	Payment recorded (paid_at).	— (pull)
void	LMN ops	Cancelled with void_reason. Stays readable; a new draft may be created for the same order and receives the next number on issue.	— (pull)	✅

OrderInvoiceSummary

Embedded as Order.invoice on every order response and on data.order.invoice of every order.* webhook. null when the order has no invoice.

Field	Type	Nullable	Notes
id	string (ULID)	no	Use with GET /v1/invoices/{invoice_id}.
number	string	yes	null while draft.
version	integer	no	0 while draft.
status	enum	no	draft | issued | paid | void.
currency	string	no	USD at launch.
total	number	yes	Current computed total on a draft (null while unresolved); frozen once issued.
issued_at	ISO 8601	yes	null while draft.
document_url	string (URL)	yes	Pinned ?version=N. null while draft.