> ## Documentation Index
> Fetch the complete documentation index at: https://developers.novatrade24.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Order creation

> Register a VIN-based transaction linked to an existing buyer.

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](/guides/buyer-onboarding)).
  Keep the `buyerUuid` from the upsert response.
* You have a unique `externalOrderId` — your system's identifier for the deal.

## Create an order

```bash theme={null}
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": "k.kaufmann@seller.example"
    },
    "vins": [
      {
        "vin": "WVWZZZ1JZXW000001",
        "brand": "Volkswagen",
        "model": "Golf",
        "mileage": 45000,
        "firstRegistrationDate": "2020-03-15",
        "purchaseAmount": { "value": 1850000, "currency": "EUR" }
      }
    ],
    "totalAmount": { "value": 1850000, "currency": "EUR" }
  }'
```

### Response

```json theme={null}
{
  "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](/concepts/rate-limits#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](/concepts/optimistic-concurrency).

```bash theme={null}
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": "klaus@seller.example"
    }
  }'
```

## Cancel an order

```bash theme={null}
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:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Invoice & Payment" icon="receipt" href="/guides/invoice-payment">
    Submit commercial data for the transaction.
  </Card>

  <Card title="Compliance rollup" icon="gauge" href="/concepts/compliance-rollup">
    Track transaction state across all modules.
  </Card>
</CardGroup>