Skip to main content
An order represents one transaction on the NT24 platform. It carries one or more VINs, links to a buyer, and is the parent resource for the invoice, payment, and transport sub-resources.

​
Prerequisites

  • A buyer already exists (see Buyer onboarding). Keep the buyerUuid from the upsert response.
  • You have a unique externalOrderId — your system’s identifier for the deal.

​
Create an order

curl -X POST "https://api.novatrade24.com/v1/partners/${SELLER_ID}/orders" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "externalOrderId": "DEAL-2026-04-00451",
    "buyerId": "a1b2c3d4-...",
    "purchaseDate": "2026-04-18",
    "responsibleContact": {
      "firstName": "Kristina",
      "lastName": "Kaufmann",
      "email": "[email protected]"
    },
    "vins": [
      {
        "vin": "WVWZZZ1JZXW000001",
        "brand": "Volkswagen",
        "model": "Golf",
        "mileage": 45000,
        "firstRegistrationDate": "2020-03-15",
        "purchaseAmount": { "value": 1850000, "currency": "EUR" }
      }
    ],
    "totalAmount": { "value": 1850000, "currency": "EUR" }
  }'

​
Response

{
  "uuid": "o1p2q3r4-...",
  "externalOrderId": "DEAL-2026-04-00451",
  "buyerId": "a1b2c3d4-...",
  "purchaseDate": "2026-04-18",
  "status": "CREATED",
  "vins": [
    {
      "vin": "WVWZZZ1JZXW000001",
      "brand": "Volkswagen",
      "model": "Golf",
      "mileage": 45000,
      "firstRegistrationDate": "2020-03-15",
      "purchaseAmount": { "value": 1850000, "currency": "EUR" },
      "complianceStatus": "PENDING"
    }
  ],
  "totalAmount": { "value": 1850000, "currency": "EUR" },
  "version": 0,
  "createdAt": "2026-04-22T10:30:00Z",
  "updatedAt": "2026-04-22T10:30:00Z"
}

​
Idempotent upsert

Orders are keyed on (sellerId, externalOrderId):
ScenarioResult
First POST with key XOrder created, 201
Second POST with key X, identical bodyCached response returned, 200
Second POST with key X, different body422 Unprocessable Entity — idempotency key reused with different payload
Different Idempotency-Key, same externalOrderId, identical bodyExisting order returned, 200
Different Idempotency-Key, same externalOrderId, different body409 Conflict — use PATCH to update
This two-layer idempotency (header + natural key) means your retry logic doesn’t create duplicates even if you lose track of your own keys.

​
Single-VIN vs multi-VIN orders

For the Santander pilot and 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. Compliance state on multi-VIN orders is tracked per-VIN inside the transport module. Some VINs may be delivered while others are still in transit; the order’s overall status reflects the aggregate.

​
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

GET /partners/{sellerId}/orders?status=TRANSPORT_IN_PROGRESS&createdAfter=2026-04-01T00:00:00Z&buyerId=a1b2c3d4-...
Standard pagination (page, size, sort=createdAt,desc) applies. See Pagination for details.

​
Update an order

PATCH /partners/{sellerId}/orders/{uuid} for mutable fields (responsibleContact, purchaseDate). Requires If-Match header with the current version for optimistic concurrency. 
curl -X PATCH "https://api.novatrade24.com/v1/partners/${SELLER_ID}/orders/${ORDER_UUID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'If-Match: "5"' \
  -H "Content-Type: application/json" \
  -d '{
    "responsibleContact": {
      "firstName": "Klaus",
      "lastName": "Neumann",
      "email": "[email protected]"
    }
  }'

​
Cancel an order

curl -X POST "https://api.novatrade24.com/v1/partners/${SELLER_ID}/orders/${ORDER_UUID}/cancel" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Buyer withdrew purchase decision" }'
Cancellation is terminal. Cancelled orders skip compliance evaluation and no longer accept invoice/payment/transport input.

​
Upload order-level documents

ORDER_PURCHASING_CONTRACT is the supported type: 
curl -X POST "https://api.novatrade24.com/v1/partners/${SELLER_ID}/orders/${ORDER_UUID}/documents" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "type=ORDER_PURCHASING_CONTRACT" \
  -F "documentDate=2026-04-18" \
  -F "signedWet=true" \
  -F "file=@/path/to/contract.pdf"

​
Next

Invoice & Payment

Submit commercial data for the transaction.

Compliance rollup

Track transaction state across all modules.