Prerequisites
- A buyer already exists (see Buyer onboarding).
Keep the
buyerUuidfrom the upsert response. - You have a unique
externalOrderId, your system’s identifier for the deal.
Create an order
Response
What the write checks on an amount
totalAmount and every VIN’s purchaseAmount are Money, and a body that
breaks its rules returns 422 and creates nothing: negative, not a whole number
of minor units (1850000.5 is refused, not rounded), or a currency other than
EUR. The same rules apply to the invoice and payment
amounts.
A read can still report a negative amount on an order a staff member edited by
hand. Only what you send through this API is bounded.
Idempotent upsert
Orders are keyed on(sellerId, externalOrderId):
This two-layer idempotency (header + natural key) means your retry logic
doesn’t create duplicates even if you lose track of your own keys.
responsibleContact is compared on its email address alone, so a body naming a
different person under an address the buyer already has is not a different
body: the order resolves to the person on file, the response’s
responsibleContact carries that person, and notApplied names the fields you
sent that the record does not say — responsibleContact.lastName and the two
beside it. The 200 of a replayed externalOrderId reports it the same way,
so a retry under a fresh Idempotency-Key is told what the order points at too.
PATCH answers the same way, and it repoints the order when the address you
sent belongs to a different live contact of the buyer than the one the order
currently holds — the order moves to that person and its version advances,
while notApplied still names what you sent that the record does not say.
Nothing is ever written to a stored contact person through this API; see
the two contact paths.
Single-VIN vs multi-VIN orders
For most direct dealer integrations, orders are single-VIN.vins is
always an array of length 1.
Multi-VIN orders (fleet deals where one invoice covers multiple vehicles)
require the allowMultiVinOrders capability flag. Without it, arrays of
length > 1 are rejected with 403.
Transport state on multi-VIN orders is reported per VIN in the transport
resource’s vins[]. When staff split an order across shipments, some VINs
may be delivered while others are still in transit; the order-level
transport status is the least advanced transport.
Look up orders
By UUID
GET /partners/{sellerId}/orders/{uuid} returns the canonical record. Use
If-None-Match with the previous ETag to get 304 Not Modified when the
order hasn’t changed.
By VIN
VIN is not globally unique, the same VIN may appear in multiple historical orders (buyback, resale).GET /partners/{sellerId}/orders?vin=WVWZZZ1JZXW000001
returns all matches scoped to your authorized partners.
By filters
page, size, sort=createdAt,desc) applies. See
Pagination for details.
An order whose buyer or seller has closed its account on Novatrade24 is
read-only: it stays readable, and update, cancellation, documents and payment
answer
409. Creating an order for an inactive buyer answers 409 as well; the
buyer’s inactiveSince tells you it closed. See
Inactive buyers.Update an order
PATCH /partners/{sellerId}/orders/{uuid} for mutable fields
(responsibleContact, purchaseDate). Requires an If-Match header carrying
the ETag you were last given, echoed back verbatim — the version integer is
not a tag and building one out of it refuses every write. See
optimistic concurrency for what does and
does not make that tag stale.
Cancel an order
Upload order-level documents
ORDER_PURCHASING_CONTRACT is the supported type:
Next
Invoice & Payment
Submit commercial data for the transaction.
Compliance rollup
Track transaction state across all modules.