Order creation

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):

Scenario	Result
First POST with key X	Order created, `201`
Second POST with key X, identical body	Cached response returned, `200`
Second POST with key X, different body	`422 Unprocessable Entity` — idempotency key reused with different payload
Different `Idempotency-Key`, same `externalOrderId`, identical body	Existing order returned, `200`
Different `Idempotency-Key`, same `externalOrderId`, different body	`409 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"

Invoice & Payment

Submit commercial data for the transaction.

Compliance rollup

Track transaction state across all modules.

Get Started

Core Concepts

Integration Guide

Webhooks

Reference

Security & Compliance

Prerequisites

Create an order

Response

Idempotent upsert

Single-VIN vs multi-VIN orders

Look up orders

By UUID

By VIN

By filters

Update an order

Cancel an order

Upload order-level documents

Next

Invoice & Payment

Compliance rollup

​Prerequisites

​Create an order

​Response

​Idempotent upsert

​Single-VIN vs multi-VIN orders

​Look up orders

​By UUID

​By VIN

​By filters

​Update an order

​Cancel an order

​Upload order-level documents

​Next

Invoice & Payment

Compliance rollup

Prerequisites

Create an order

Response

Idempotent upsert

Single-VIN vs multi-VIN orders

Look up orders

By UUID

By VIN

By filters

Update an order

Cancel an order

Upload order-level documents

Next