# Bestellungen

Die Orders-API verwaltet Käufe, Bestellstatus, Weiterleitung an Verkäufer-Shops und Versandaktualisierungen.

## Was ist eine Bestellung?

Eine Bestellung ist ein laufender oder abgeschlossener Kauf in einem oder mehreren Verkäufer-Shops. Beim Checkout erstellt Tradly einen übergeordneten Datensatz mit Zahlungsdaten, Kundeninformationen, Lieferadresse und Summen (`list_total`, `offer_total`, `shipping_total`, `tax_total`, `grand_total`). Er enthält `Order Details` als Positionen für Listings/Varianten. Bei mehreren Verkäufern werden Artikel den Shop-Konten (`account_id`) zugeordnet; Sendungen verfolgen die Abwicklung je Verkäufer.

## Bestellstatus

| ID | Status | Beschreibung |
|---:|---|---|
| `0` | `Draft` | Entwurf vor dem Checkout des Warenkorbs. |
| `1` | `Incomplete` | Erstellung läuft; noch nicht bezahlt. |
| `2` | `Order Placed` | Bestellung aufgegeben und Zahlung bestätigt; wartet auf Verkäufer. |
| `3` | `In Process` | Verkäufer hat angenommen und bearbeitet die Bestellung. |
| `4` | `Shipped` | Artikel mit Sendungsverfolgung versandt. |
| `5` | `Delivered` | Bestellung am Ziel zugestellt. |
| `6` | `Cancelled by Customer` | Vor der Abwicklung vom Kunden storniert. |
| `7` | `Cancelled by Admin` | Vom Tenant-Admin oder Verkäufer storniert. |
| `8` | `Completed` | Transaktion abgeschlossen. |

## Sendungsstatus

| ID | Status | Beschreibung |
|---:|---|---|
| `1` | `Created` | Sendungsdatensatz für Bestellpositionen erstellt. |
| `2` | `In Progress` | Verkäufer verpackt die Artikel. |
| `3` | `Shipped` | Sendung an den Zusteller übergeben. |
| `4` | `Ready for Pickup` | Abholung beim Verkäufer oder durch den Zusteller möglich. |
| `5` | `Out for Delivery` | Zusteller bringt das Paket zum Kunden. |
| `6` | `Undelivered / Returned` | Zustellung fehlgeschlagen; Rücksendung an Absender. |
| `7` | `Delivered` | Zusteller hat die Lieferung bestätigt. |
| `8` | `Delivered & Confirmed` | Kunde/Admin hat den Erhalt bestätigt. |
| `9` | `Customer Return Initiated` | Käufer hat Rückgabe oder Umtausch beantragt. |
| `10` | `Customer Return Picked` | Zusteller hat die Rücksendung abgeholt. |
| `11` | `Customer Return Confirmed` | Verkäufer hat Rückware erhalten und geprüft. |
| `12` | `Cancelled by Account` | Verkäuferkonto hat die Sendung storniert. |
| `13` | `Cancelled by Customer` | Kunde hat die Sendung storniert. |
| `14` | `Arrived at Location` | Paket an Umschlagplatz oder Abholstation eingetroffen. |
| `15` | `Cancelled by Admin` | Tenant-Admin hat die Sendung storniert. |

## Zahlungsstatus

| ID | Status | Beschreibung |
|---:|---|---|
| `1` | `Unpaid / Pending` | Zahlung noch nicht eingezogen. |
| `2` | `Paid` | Zahlung erfolgreich eingezogen. |
| `3` | `Failed` | Zahlungsversuch fehlgeschlagen. |
| `4` | `Refunded` | Zahlung an den Kunden erstattet. |

## Bestellobjekt

Das Objekt enthält Summen, Kundenprofil, Zahlungs- und Versanddetails, Artikel, Verkäufererlöse und Sendungsverfolgung.

- Kernfelder: `id`, `reference_number`, `tenant_id`, `user_id`, `user` (Profil), `account_ids`, `order_status`, `order_status_description`, `payment_status`, `payment_status_description`, `completed`, `currency` (3-stelliger ISO-Code), `created_at`, `updated_at` (Unix-Zeitstempel).
- Geldbeträge sind `{ amount, formatted }`-Objekte. `list_total` ist der ursprüngliche Zwischensummenbetrag, `offer_total` nach Rabatten, `tax_total` und `shipping_total` sind Steuer und Versand, `grand_total` entspricht `offer_total + shipping_total + tax_total`.
- `customer_pricing` zeigt die Aufschlüsselung für Käufer (`grand_total`, `customer_sub_total`, `customer_shipping_charge`, `customer_tax`, `customer_coupon`). `account_pricing` zeigt bei Filterung nach `account_id` Verkäufererlöse, Provision, Versand und Steuer.
- `payment_method` enthält `id`, `name`, `type`, `gateway_name`; `shipping_method` enthält `id`, `name`, `type`, `shipping_charge`; `shipping_address` die Zustelladresse; `shipment` aktive Sendungsverfolgung (`shipment_status`, `tracking_number`, `courier_name`, `shipped_at`, `delivered_at`).

### Positionen (`order_details`)

Jede Position repräsentiert einen gekauften Artikel und enthält `id`, `listing_id`, `quantity`, Beträge `list_price`, `offer_price`, `special_price`, `tax_charges`, `shipping_charges`, Buchungsdaten `schedule_start_at`/`schedule_end_at`, `listing`-Objekt, `variant`, ausgewählte `order_detail_attributes` und pro Einheit erfasste `order_detail_item_attributes`.