API: Bestellungen
Bestellungen über die REST-API anlegen und abrufen, mit Bestandsprüfung, Überverkauf, Sendungsnummern und Schutz vor doppelten Bestellungen.
Rechte: orders:read zum Lesen, orders:write zum Anlegen. Grundlagen zu Schlüssel und Antworten: API: Überblick und Zugang.
Endpunkte
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /v1/orders | Bestellungen auflisten |
| GET | /v1/orders/{id} | Eine Bestellung, per ID, Bestellnummer oder eigener Nummer (externalId) |
| POST | /v1/orders | Bestellung anlegen |
Bestellung anlegen
POST /v1/orders
{
"externalId": "100245",
"orderedAt": "2026-10-09T14:12:00Z",
"customer": { "email": "kunde@example.com", "firstName": "Lena", "lastName": "Albrecht" },
"shippingAddress": {
"firstName": "Lena", "lastName": "Albrecht",
"address1": "Hafenstraße 12", "zip": "20457", "city": "Hamburg", "countryCode": "DE"
},
"lineItems": [
{ "sku": "SH-KNIT-NAV-M", "quantity": 1 },
{ "sku": "HS-TEE-WHT-M", "quantity": 2, "unitPrice": 22.90 }
],
"shippingPrice": 4.90,
"paid": true
}| Feld | Inhalt |
|---|---|
externalId | Nummer im eigenen System, Pflicht. Die Bestellnummer in Trade Bridge NEO ist Präfix der Verbindung + diese Nummer. |
orderedAt | Bestellzeitpunkt (ISO 8601), sonst jetzt |
customer | email, firstName, lastName, phone, language |
shippingAddress | Pflicht: address1, zip, city, countryCode und lastName oder company; dazu firstName, address2, phone, email |
billingAddress | Wie die Lieferadresse, zusätzlich vatId; fehlt sie, gilt die Lieferadresse |
lineItems | Positionen mit sku und quantity; optional unitPrice (brutto, sonst Verkaufspreis der Variante), discount (brutto, gesamt) und taxRate (Prozent, sonst nach Lieferland) |
shippingPrice | Versandkosten brutto, Standard 0 |
currency | Standard EUR |
paid | Bereits bezahlt, Standard true. Mit false steht die Bestellung als unbezahlt in Trade Bridge NEO. |
note | Notiz an der Bestellung |
allowOutOfStock | true legt die Bestellung auch ohne ausreichenden Bestand an |
Die Bestellung läuft danach wie jede andere durch Trade Bridge NEO: Lager, Versand, Rechnung und Buchhaltung.
Bestand und Überverkauf
Vor dem Anlegen prüft die API je Artikel den verfügbaren Bestand. Reicht er nicht und ist an der Variante der Überverkauf aus, wird die Bestellung abgelehnt:
409
{
"error": {
"code": "insufficient_stock",
"message": "Nicht genug Bestand und Überverkauf ist für diese Artikel aus. …",
"shortages": [{ "sku": "HS-TEE-WHT-M", "requested": 2, "available": 1 }]
}
}Artikel mit erlaubtem Überverkauf oder ohne Bestandsführung blockieren nie. Mit "allowOutOfStock": true wird die Bestellung auf jeden Fall angelegt, etwa wenn das eigene System den Verkauf schon zugesagt hat.
Keine doppelten Bestellungen
Kommt dieselbe externalId ein zweites Mal, legt die API nichts neu an. Sie antwortet mit 200 und der vorhandenen Bestellung ("created": false) statt 201. Eine Anfrage nach einem Netzwerkfehler darf also einfach wiederholt werden.
Bestellungen abrufen
GET /v1/orders kennt diese Parameter:
| Parameter | Bedeutung |
|---|---|
updated_since | Nur Bestellungen, die sich seitdem geändert haben, älteste Änderung zuerst |
source=own | Nur Bestellungen, die über diese Verbindung kamen |
limit, offset | Blättern, höchstens 100 je Seite (Standard 50) |
Ohne updated_since kommen die zuletzt geänderten zuerst.
Felder einer Bestellung
| Feld | Inhalt |
|---|---|
id, name | ID und Bestellnummer in Trade Bridge NEO |
externalId | Eigene Nummer, wenn die Bestellung über diese Verbindung kam |
channel | Verkaufskanal |
financialStatus | Zahlstatus, z. B. PAID oder PENDING |
fulfillmentStatus | Versandstatus, z. B. FULFILLED; leer = offen |
cancelled, cancelledAt | Storniert und wann |
holdUntil | Versand zurückgehalten bis |
totalPrice, subtotalPrice, totalTax, totalDiscounts, shippingPrice | Beträge brutto |
shippingAddress, billingAddress | Adressen |
lineItems | Positionen mit sku, title, quantity, unitPrice, discount |
shipments | Lieferscheine mit packages: carrier, trackingNumber, trackingUrl, status, deliveredAt |
orderedAt, createdAt, updatedAt | Zeitpunkte (ISO 8601) |
Über shipments holt sich das eigene System die Sendungsnummern, sobald die Ware unterwegs ist.