# Bestellungen API

> Bestellungen Ihres Shops senden, um Umsätze E-Mails zuzuordnen und Kaufprofile aufzubauen.

Basis-URL: `https://api.emailit.com/v2`. Authentifizieren Sie sich mit `Authorization: Bearer <API key>`.

## Bestellung erstellen oder aktualisieren — POST /orders

> Senden Sie eine Bestellung aus Ihrem Shop. Emailit ordnet neue Bestellungen der E-Mail zu, die der Käufer zuletzt geklickt oder geöffnet hat, aktualisiert sein Kaufprofil und löst order.placed aus. Alpha: nur für das Emailit-Team zugänglich.

# Bestellung erstellen oder aktualisieren

Senden Sie eine Bestellung aus dem Backend Ihres Shops. Die Bestellung wird über ihre `id` in Ihrem Shop identifiziert: Senden Sie dieselbe `id` erneut, wird stattdessen die gespeicherte Bestellung aktualisiert. Erfordert einen API-Schlüssel mit dem Scope `full` oder `events`. Bei einem Schlüssel mit dem Scope `events` enthält die Antwort nur `object`, `id` und `external_id`.

> **Commerce ist in der Alpha:** Commerce steht nur dem Emailit-Team offen, solange wir es testen. Andere Anfragen geben `403` mit `error: "commerce_alpha"` zurück. API-Schlüssel funktionieren nur in Workspaces, die dem Emailit-Team gehören. Siehe [Wer Commerce nutzen kann](/de/docs/commerce/#who-can-use-commerce).

Wenn eine Bestellung zum ersten Mal gespeichert wird, geschieht Folgendes:

- Emailit ordnet sie der Kampagnen- oder Automatisierungs-E-Mail zu, die der Käufer zuletzt innerhalb des Klickfensters vor `placed_at` geklickt oder, ohne Klick, zuletzt innerhalb des Öffnungsfensters geöffnet hat. Die Fenster stehen in den [Commerce-Einstellungen](/de/docs/api-reference/commerce/get-settings/). Siehe [Wie Bestellungen E-Mails zugeordnet werden](/de/docs/commerce/#how-orders-are-credited-to-emails).
- Emailit verknüpft sie mit dem Kontakt des Käufers und erstellt den Kontakt bei Bedarf (siehe `create_contact`).
- Der in `cart_id` angegebene Warenkorb wird als konvertiert markiert, ebenso die anderen offenen Warenkörbe des Käufers, die zuletzt vor der Bestellung aktualisiert wurden.
- Passende Gutscheincodes werden als eingelöst markiert.
- Die Kaufkennzahlen des Kontakts werden aktualisiert.
- Emailit löst [`order.placed`](/de/docs/webhooks/events/order/placed/) aus, das Webhooks und Automatisierungen empfangen.

Wenn Sie eine bereits gespeicherte Bestellung senden, wird sie aktualisiert und [`order.updated`](/de/docs/webhooks/events/order/updated/) ausgelöst, mit `previous_status`, wenn sich der Status geändert hat. Die Zuordnung ändert sich nicht. Nur die Felder, die Sie senden, ändern sich: `status`, `placed_at`, `currency`, die Beträge, `coupon_codes`, `cart_id` und `items` behalten ihre gespeicherten Werte, wenn Sie sie weglassen, `metadata` wird mit dem gespeicherten Objekt zusammengeführt, und `total` ist nicht erforderlich. Wenn Sie `items` senden, werden alle Artikel ersetzt. Um nur den Status oder eine Rückerstattung zu ändern, können Sie auch [Bestellung aktualisieren](/de/docs/api-reference/orders/update/) verwenden.

Um frühere Bestellungen zu importieren, ohne sie E-Mails zuzuordnen oder Automatisierungen zu starten, verwenden Sie [Bestellungen gesammelt importieren](/de/docs/api-reference/orders/batch/).

`POST /orders`

## Anfrage-Body

- `id` (string | number, erforderlich): Die Bestell-ID in Ihrem Shop, bis zu 255 Zeichen. Zahlen werden als Strings gespeichert. Wird als `external_id` gespeichert. Sie können sie auch als `external_id` oder `order_id` senden.

- `email` (string): Die E-Mail-Adresse des Käufers. Wird in Kleinbuchstaben gespeichert. Emailit verwendet sie, um den Kontakt zu finden und die Bestellung einer an diese Adresse gesendeten E-Mail zuzuordnen. `customer.email` wird ebenfalls akzeptiert.

- `contact_id` (string): Der Kontakt des Käufers (`con_...`). Wenn kein Kontakt diese ID hat, sucht Emailit den Kontakt über `email`.

- `first_name` (string): Der Vorname des Käufers, bis zu 191 Zeichen. Wird verwendet, wenn Emailit den Kontakt erstellt. `customer.first_name` wird ebenfalls akzeptiert.

- `last_name` (string): Der Nachname des Käufers, bis zu 191 Zeichen. Wird verwendet, wenn Emailit den Kontakt erstellt. `customer.last_name` wird ebenfalls akzeptiert.

- `status` (string): `placed` (Standardwert), `paid`, `fulfilled`, `canceled` oder `refunded`. Wenn eine Bestellung zum ersten Mal `paid`, `fulfilled`, `canceled` oder `refunded` hat, setzt Emailit das passende Feld `paid_at`, `fulfilled_at`, `canceled_at` oder `refunded_at` auf die aktuelle Zeit. Stornierte Bestellungen zählen nicht zum Umsatz.

- `currency` (string): Dreistelliger Code nach ISO 4217. Standardmäßig gilt die Währung des Workspaces aus den [Commerce-Einstellungen](/de/docs/api-reference/commerce/get-settings/). Beträge werden nie umgerechnet: Berichte gruppieren den Umsatz nach Währung.

- `total` (number | string): Bestellsumme. Erforderlich bei einer neuen Bestellung ohne Artikel. Ohne sie berechnet Emailit die Summe der Positionsbeträge abzüglich `discount`, zuzüglich `shipping` und `tax`, nie unter 0. Beträge sind Zahlen oder numerische Strings, können nicht negativ sein und werden mit bis zu 4 Nachkommastellen gespeichert.

- `subtotal` (number | string): Betrag vor Rabatt, Versandkosten und Steuern. Standardwert bei Bestellungen mit Artikeln: die Summe der Positionsbeträge.

- `discount` (number | string): Rabattbetrag als positive Zahl.

- `shipping` (number | string): Versandkosten.

- `tax` (number | string): Steuerbetrag.

- `refunded_amount` (number | string): Erstatteter Betrag. Standardwert `0` oder `total`, wenn `status` `refunded` ist. Der Umsatz ist `total` abzüglich `refunded_amount`.

- `coupon_codes` (string[]): Bis zu 20 Gutschein- oder Rabattcodes, die in der Bestellung verwendet wurden. Ein Code, der ohne Beachtung der Groß-/Kleinschreibung einem [Gutscheincode](/de/docs/api-reference/coupons/list-codes/) im Workspace entspricht, wird als durch diese Bestellung eingelöst markiert. `coupon_code` und `discount_codes` werden ebenfalls akzeptiert.

- `cart_id` (string): Die Warenkorb- oder Checkout-ID in Ihrem Shop, aus der die Bestellung stammt. Der [Warenkorb](/de/docs/api-reference/carts/upsert/) mit dieser ID wird `converted`.

- `placed_at` (string | number): Zeitpunkt, zu dem die Bestellung aufgegeben wurde: ein Datum mit Uhrzeit im Format ISO 8601 oder ein Unix-Zeitstempel in Sekunden (Millisekunden funktionieren ebenfalls). Standardwert: die aktuelle Zeit. Darf höchstens 24 Stunden in der Zukunft liegen. `created_at` wird ebenfalls akzeptiert.

- `items` (object[]): Bis zu 250 Positionen. `line_items` wird ebenfalls akzeptiert. Jeder Artikel hat: - `product_id` (string oder number): die Produkt-ID in Ihrem Shop. Artikel ohne `title`, `url`, `image_url` oder `categories` übernehmen diese aus dem [Katalog](/de/docs/api-reference/products/create/). `id` wird ebenfalls akzeptiert. - `variant_id`, `sku` (string): bis zu 255 Zeichen. - `title` (string): bis zu 500 Zeichen. Erforderlich, wenn der Artikel weder `product_id` noch `sku` hat. `name` wird ebenfalls akzeptiert. - `quantity` (integer): 1 oder mehr. Standardwert 1. - `price` (number oder string): der Stückpreis. Standardwert 0. `unit_price` wird ebenfalls akzeptiert. - `total` (number oder string): der Positionsbetrag. Standardwert: `price` mal `quantity`. - `categories` (string[]): bis zu 50 Kategorienamen. - `url`, `image_url` (string): `http`- oder `https`-URLs.

- `metadata` (object): Ihre eigenen Schlüssel-Wert-Daten, bis zu 16 KB als JSON. Bei Aktualisierungen werden die gesendeten Schlüssel mit dem gespeicherten Objekt zusammengeführt.

- `create_contact` (boolean): Standardwert `true`: Wenn kein Kontakt zu `contact_id` oder `email` passt, erstellt Emailit einen aus `email`, `first_name` und `last_name` und löst `contact.created` aus. Der neue Kontakt wird bei keiner Kontaktliste angemeldet, daher erreichen ihn Kampagnen nicht. Setzen Sie den Wert auf `false`, um nie einen Kontakt zu erstellen: Die Bestellung wird dann nur mit einem bereits existierenden Kontakt verknüpft.

- `accepts_marketing` (boolean): Setzen Sie den Wert zusammen mit `audience_id` auf `true`, wenn der Käufer dem Erhalt von Marketing-E-Mails zugestimmt hat. Emailit meldet den Kontakt dann bei dieser Kontaktliste an, sofern er nicht bereits darin ist. Standardwert `false`.

- `audience_id` (string): Die Kontaktliste (`aud_...`), bei der der Käufer angemeldet wird, wenn `accepts_marketing` `true` ist. Wenn die Kontaktliste nicht existiert oder das Abonnentenlimit Ihres Tarifs erreicht ist, wird die Bestellung trotzdem gespeichert und der Kontakt nicht angemeldet.

- `email_id` (string): Die Kampagnen-E-Mail (`eml_...`), über die der Käufer gekommen ist, falls Ihr Shop sie erfasst. Wird nur bei neuen Bestellungen verwendet, und nur IDs, die mit `eml_` beginnen, werden gelesen. Die Bestellung wird dieser E-Mail zugeordnet, wenn sie eine Kampagnen-E-Mail des Workspaces ist und entweder einen Klick innerhalb des Klickfensters vor der Bestellung hat oder innerhalb dieses Fensters gesendet wurde. Andernfalls ordnet Emailit die Bestellung wie üblich zu. `attribution.email_id` wird ebenfalls akzeptiert.

## Rückgabe

`201 Created` mit dem [Bestell-Objekt](/de/docs/api-reference/orders/get/), wenn die Bestellung neu ist, oder `200 OK`, wenn eine bestehende Bestellung aktualisiert wurde. Gibt `422` zurück, wenn ein Feld ungültig ist.
**Anfrage** `POST /orders`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/orders \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1042",
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "status": "paid",
    "currency": "USD",
    "discount": 10.7,
    "shipping": 5,
    "tax": 0,
    "coupon_codes": ["WELCOME-7KQ2M9XA"],
    "cart_id": "c-58f1a2",
    "placed_at": "2026-10-08T14:32:10Z",
    "items": [
      { "product_id": "8123456789", "variant_id": "42-blue", "sku": "TRS-BLU-42", "title": "Trail running shoe", "quantity": 1, "price": 89 },
      { "product_id": "8123456790", "title": "Merino running socks", "quantity": 2, "price": 9 }
    ],
    "metadata": { "channel": "web" },
    "accepts_marketing": true,
    "audience_id": "aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV"
  }'
```

**201**

```json
{
  "object": "order",
  "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
  "external_id": "1042",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "paid",
  "currency": "USD",
  "subtotal": 107,
  "discount": 10.7,
  "shipping": 5,
  "tax": 0,
  "total": 101.3,
  "refunded_amount": 0,
  "coupon_codes": [
    "WELCOME-7KQ2M9XA"
  ],
  "cart_id": "c-58f1a2",
  "source": "api",
  "placed_at": "2026-10-08T14:32:10.000Z",
  "paid_at": "2026-10-08T14:32:11.204Z",
  "fulfilled_at": null,
  "canceled_at": null,
  "refunded_at": null,
  "attribution": {
    "email_id": "eml_3TSvDAUQi7vqxvAQ1UEVN7k4igq",
    "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
    "campaign_name": "October newsletter",
    "variant_id": null,
    "automation_id": null,
    "automation_name": null,
    "type": "click",
    "touched_at": "2026-10-08T09:41:52.000Z"
  },
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "categories": [
        "Shoes",
        "Running"
      ],
      "url": "https://shop.example.com/products/trail-running-shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
    },
    {
      "product_id": "8123456790",
      "variant_id": null,
      "sku": null,
      "title": "Merino running socks",
      "quantity": 2,
      "unit_price": 9,
      "total": 18,
      "categories": [
        "Accessories"
      ],
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg"
    }
  ],
  "metadata": {
    "channel": "web"
  },
  "created_at": "2026-10-08T14:32:11.204Z",
  "updated_at": "2026-10-08T14:32:11.204Z"
}
```

**422**

```json
{
  "message": "Validation failed. items.1.quantity: must be a positive integer",
  "errors": {
    "items.1.quantity": [
      "must be a positive integer"
    ]
  }
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/orders/create/

## Bestellung abrufen — GET /orders/{id}

> Rufen Sie eine Bestellung mit ihren Artikeln und der Kampagnen- oder Automatisierungs-E-Mail ab, der sie zugeordnet ist. Alpha: nur für das Emailit-Team zugänglich.

# Bestellung abrufen

Ruft eine Bestellung über ihre Emailit-ID oder über die Bestell-ID in Ihrem Shop ab, mit ihren Artikeln und ihrer Zuordnung. Erfordert einen API-Schlüssel mit dem Scope `full`.

> **Commerce ist in der Alpha:** Commerce steht nur dem Emailit-Team offen, solange wir es testen. Andere Anfragen geben `403` mit `error: "commerce_alpha"` zurück. API-Schlüssel funktionieren nur in Workspaces, die dem Emailit-Team gehören. Siehe [Wer Commerce nutzen kann](/de/docs/commerce/#who-can-use-commerce).

`GET /orders/{id}`

## Pfadparameter

- `id` (string, erforderlich): Die Bestell-ID (`ord_...`) oder die Bestell-ID in Ihrem Shop (`external_id`). Shop-IDs mit Sonderzeichen müssen Sie URL-kodieren.

## Das Bestell-Objekt

- `object` (string): Immer `order`.

- `id` (string): Emailit-Bestell-ID (`ord_...`).

- `external_id` (string): Die Bestell-ID in Ihrem Shop: die `id`, die Sie gesendet haben.

- `contact_id` (string | null): Der Kontakt des Käufers (`con_...`) oder `null`, wenn die Bestellung mit keinem Kontakt verknüpft ist.

- `email` (string | null): Die E-Mail-Adresse des Käufers, in Kleinbuchstaben.

- `status` (string): `placed`, `paid`, `fulfilled`, `canceled` oder `refunded`.

- `currency` (string): Dreistelliger Code nach ISO 4217 für die Beträge.

- `subtotal` (number | null): Summe der Artikel vor Rabatt, Versandkosten und Steuern.

- `discount` (number | null): Rabattbetrag.

- `shipping` (number | null): Versandkosten.

- `tax` (number | null): Steuerbetrag.

- `total` (number): Bestellsumme. Der Umsatz in Berichten ist `total` abzüglich `refunded_amount`, und stornierte Bestellungen zählen nicht.

- `refunded_amount` (number): Bisher erstatteter Betrag. `0`, wenn nichts erstattet wurde.

- `coupon_codes` (string[]): In der Bestellung verwendete Gutschein- oder Rabattcodes.

- `cart_id` (string | null): Die Warenkorb- oder Checkout-ID in Ihrem Shop, aus der die Bestellung stammt.

- `source` (string): Wie die Bestellung zu Emailit gelangt ist: `api`, `js` (das Tracking-Skript) oder `import` ([Sammelimport](/de/docs/api-reference/orders/batch/)).

- `placed_at` (string): Zeitpunkt, zu dem die Bestellung aufgegeben wurde, im Format ISO 8601 in UTC.

- `paid_at, fulfilled_at, canceled_at, refunded_at` (string | null): Zeitpunkt, zu dem Emailit die Bestellung zum ersten Mal mit diesem Status gespeichert hat. Wird einmal gesetzt und nicht geleert, wenn sich der Status erneut ändert.

- `attribution` (object | null): Die E-Mail, der die Bestellung zugeordnet ist, oder `null`. Wird einmal gesetzt, wenn die Bestellung zum ersten Mal gespeichert wird. Siehe [Wie Bestellungen E-Mails zugeordnet werden](/de/docs/commerce/#how-orders-are-credited-to-emails). - `email_id` (string): die zugeordnete E-Mail. - `campaign_id`, `campaign_name` (string oder null): ihre Kampagne. - `variant_id` (string oder null): die Version des A/B-Tests (`cvr_...`), die der Käufer erhalten hat. - `automation_id`, `automation_name` (string oder null): ihre Automatisierung. - `type` (string): `click` oder `open`. - `touched_at` (string oder null): Zeitpunkt des Klicks oder der Öffnung.

- `items` (object[]): Positionen. Jede hat `product_id` (die Produkt-ID in Ihrem Shop), `variant_id`, `sku`, `title`, `quantity`, `unit_price`, `total`, `categories`, `url` und `image_url`.

- `metadata` (object): Ihre eigenen Schlüssel-Wert-Daten.

- `created_at, updated_at` (string): Zeitpunkt, zu dem Emailit die Bestellung gespeichert hat, und Zeitpunkt ihrer letzten Änderung, im Format ISO 8601 in UTC.

**Anfrage** `GET /orders/{id}`

**cURL**

```bash
curl https://api.emailit.com/v2/orders/ord_3aMEK4No62Zw8S1fcHNznAnnbfp \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "object": "order",
  "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
  "external_id": "1042",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "paid",
  "currency": "USD",
  "subtotal": 107,
  "discount": 10.7,
  "shipping": 5,
  "tax": 0,
  "total": 101.3,
  "refunded_amount": 0,
  "coupon_codes": [
    "WELCOME-7KQ2M9XA"
  ],
  "cart_id": "c-58f1a2",
  "source": "api",
  "placed_at": "2026-10-08T14:32:10.000Z",
  "paid_at": "2026-10-08T14:32:11.204Z",
  "fulfilled_at": null,
  "canceled_at": null,
  "refunded_at": null,
  "attribution": {
    "email_id": "eml_3TSvDAUQi7vqxvAQ1UEVN7k4igq",
    "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
    "campaign_name": "October newsletter",
    "variant_id": null,
    "automation_id": null,
    "automation_name": null,
    "type": "click",
    "touched_at": "2026-10-08T09:41:52.000Z"
  },
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "categories": [
        "Shoes",
        "Running"
      ],
      "url": "https://shop.example.com/products/trail-running-shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
    },
    {
      "product_id": "8123456790",
      "variant_id": null,
      "sku": null,
      "title": "Merino running socks",
      "quantity": 2,
      "unit_price": 9,
      "total": 18,
      "categories": [
        "Accessories"
      ],
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg"
    }
  ],
  "metadata": {
    "channel": "web"
  },
  "created_at": "2026-10-08T14:32:11.204Z",
  "updated_at": "2026-10-08T14:32:11.204Z"
}
```

**404**

```json
{
  "error": "Order not found",
  "message": "Order not found."
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/orders/get/

## Bestellung aktualisieren — POST /orders/{id}

> Ändern Sie den Status einer Bestellung, erfassen Sie eine Rückerstattung oder fügen Sie Metadaten hinzu, ohne die ganze Bestellung erneut zu senden. Alpha: nur für das Emailit-Team zugänglich.

# Bestellung aktualisieren

Ändert den Status einer gespeicherten Bestellung, erfasst eine Rückerstattung oder fügt Metadaten hinzu. Alles andere bleibt unverändert, einschließlich der Artikel und der Zuordnung. Die Kaufkennzahlen des Käufers werden neu berechnet, und Emailit löst [`order.updated`](/de/docs/webhooks/events/order/updated/) aus, mit dem `previous_status` der Bestellung, wenn sich der Status geändert hat. Erfordert einen API-Schlüssel mit dem Scope `full` oder `events`. Bei einem Schlüssel mit dem Scope `events` enthält die Antwort nur `object`, `id` und `external_id`.

> **Commerce ist in der Alpha:** Commerce steht nur dem Emailit-Team offen, solange wir es testen. Andere Anfragen geben `403` mit `error: "commerce_alpha"` zurück. API-Schlüssel funktionieren nur in Workspaces, die dem Emailit-Team gehören. Siehe [Wer Commerce nutzen kann](/de/docs/commerce/#who-can-use-commerce).

`POST /orders/{id}`

## Pfadparameter

- `id` (string, erforderlich): Die Bestell-ID (`ord_...`) oder die Bestell-ID in Ihrem Shop.

## Anfrage-Body

Senden Sie mindestens eines dieser Felder.

- `status` (string): `placed`, `paid`, `fulfilled`, `canceled` oder `refunded`. Wenn die Bestellung zum ersten Mal `paid`, `fulfilled`, `canceled` oder `refunded` erhält, wird das passende Feld `paid_at`, `fulfilled_at`, `canceled_at` oder `refunded_at` auf die aktuelle Zeit gesetzt. Stornierte Bestellungen zählen nicht zum Umsatz.

- `refunded_amount` (number | string): Der bisher insgesamt erstattete Betrag, nicht der Betrag dieser Rückerstattung. Kann nicht negativ sein. Der Umsatz ist `total` abzüglich `refunded_amount`. Wenn Sie `status` ohne `refunded_amount` auf `refunded` setzen und zuvor nichts erstattet wurde, gilt der gesamte Betrag `total` als erstattet.

- `metadata` (object): Schlüssel, die mit den Metadaten der Bestellung zusammengeführt werden. Bis zu 16 KB als JSON.

## Rückgabe

`200 OK` mit dem aktualisierten [Bestell-Objekt](/de/docs/api-reference/orders/get/). Gibt `404` zurück, wenn keine Bestellung zu `id` passt, und `422`, wenn der Body leer oder ein Feld ungültig ist.
**Anfrage** `POST /orders/{id}`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/orders/1042 \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "refunded_amount": 18 }'
```

**200**

```json
{
  "object": "order",
  "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
  "external_id": "1042",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "paid",
  "currency": "USD",
  "subtotal": 107,
  "discount": 10.7,
  "shipping": 5,
  "tax": 0,
  "total": 101.3,
  "refunded_amount": 18,
  "coupon_codes": [
    "WELCOME-7KQ2M9XA"
  ],
  "cart_id": "c-58f1a2",
  "source": "api",
  "placed_at": "2026-10-08T14:32:10.000Z",
  "paid_at": "2026-10-08T14:32:11.204Z",
  "fulfilled_at": null,
  "canceled_at": null,
  "refunded_at": null,
  "attribution": {
    "email_id": "eml_3TSvDAUQi7vqxvAQ1UEVN7k4igq",
    "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
    "campaign_name": "October newsletter",
    "variant_id": null,
    "automation_id": null,
    "automation_name": null,
    "type": "click",
    "touched_at": "2026-10-08T09:41:52.000Z"
  },
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "categories": [
        "Shoes",
        "Running"
      ],
      "url": "https://shop.example.com/products/trail-running-shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
    },
    {
      "product_id": "8123456790",
      "variant_id": null,
      "sku": null,
      "title": "Merino running socks",
      "quantity": 2,
      "unit_price": 9,
      "total": 18,
      "categories": [
        "Accessories"
      ],
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg"
    }
  ],
  "metadata": {
    "channel": "web"
  },
  "created_at": "2026-10-08T14:32:11.204Z",
  "updated_at": "2026-10-10T08:05:39.871Z"
}
```

**404**

```json
{
  "error": "Order not found",
  "message": "Order not found."
}
```

**422**

```json
{
  "message": "Validation failed. status: is required",
  "errors": {
    "status": [
      "is required"
    ]
  }
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/orders/update/

## Bestellungen auflisten — GET /orders

> Listen Sie Bestellungen auf, neueste zuerst, gefiltert nach Käufer, Status, Zeitraum oder der Kampagne oder Automatisierung, der sie zugeordnet sind. Alpha: nur für das Emailit-Team zugänglich.

# Bestellungen auflisten

Listet Bestellungen mit ihren Artikeln auf, die zuletzt aufgegebenen zuerst. Erfordert einen API-Schlüssel mit dem Scope `full`.

> **Commerce ist in der Alpha:** Commerce steht nur dem Emailit-Team offen, solange wir es testen. Andere Anfragen geben `403` mit `error: "commerce_alpha"` zurück. API-Schlüssel funktionieren nur in Workspaces, die dem Emailit-Team gehören. Siehe [Wer Commerce nutzen kann](/de/docs/commerce/#who-can-use-commerce).

`GET /orders`

## Query-Parameter

- `page` (integer): Seitennummer für die Paginierung (Minimum: 1, Standardwert: 1).

- `limit` (integer): Anzahl der zurückgegebenen Bestellungen (Minimum: 1, Maximum: 100, Standardwert: 25).

- `search` (string): Abgleich mit der Bestell-ID in Ihrem Shop oder der E-Mail-Adresse des Käufers, ohne Beachtung der Groß-/Kleinschreibung.

- `contact_id` (string): Nur Bestellungen dieses Kontakts (`con_...`).

- `email` (string): Nur Bestellungen mit dieser E-Mail-Adresse des Käufers, ohne Beachtung der Groß-/Kleinschreibung.

- `status` (string): Nur Bestellungen mit diesem Status: `placed`, `paid`, `fulfilled`, `canceled` oder `refunded`.

- `campaign_id` (string): Nur Bestellungen, die dieser Kampagne zugeordnet sind (`cmp_...`).

- `automation_id` (string): Nur Bestellungen, die dieser Automatisierung zugeordnet sind (`aut_...`).

- `attributed` (boolean): `true` für Bestellungen, die einer E-Mail zugeordnet sind, `false` für Bestellungen ohne Zuordnung.

- `from` (string): Nur Bestellungen, die zu diesem Zeitpunkt oder danach aufgegeben wurden. Ein Datum oder Datum mit Uhrzeit im Format ISO 8601; alles andere gibt `422` zurück.

- `to` (string): Nur Bestellungen, die zu diesem Zeitpunkt oder davor aufgegeben wurden. Ein Datum oder Datum mit Uhrzeit im Format ISO 8601; alles andere gibt `422` zurück.

- `match` (string): `all` (Standardwert) verlangt, dass jeder Filter `key.condition` zutrifft. Bei `or` genügt einer davon. Siehe [Filtern und Sortieren](/de/docs/api-reference/filtering/).

- `sort` (string): Sortierschlüssel: `placed_at` (Standardwert), `total` oder `created_at`.

- `order` (string): Sortierrichtung: `asc` oder `desc` (Standardwert).

## Filter

Filter- und Sortierschlüssel: siehe [Filtern und Sortieren](https://emailit.com/de/docs/api-reference/filtering/).

Bei diesem Endpunkt akzeptiert `order` nur `asc` oder `desc`. Übergeben Sie den Sortierschlüssel in `sort`, zum Beispiel `sort=total&order=desc`.

## Rückgabe

Eine Seite mit [Bestell-Objekten](/de/docs/api-reference/orders/get/) in `data`, dazu `total_records`, `next_page_url` und `previous_page_url`. Die Seiten-URLs enthalten nur `page` und `limit`; fügen Sie Ihre Suche und Filter daher erneut hinzu, wenn Sie ihnen folgen.
**Anfrage** `GET /orders`

**cURL**

```bash
curl "https://api.emailit.com/v2/orders?campaign_id=cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN&from=2026-10-01&limit=25" \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "data": [
    {
      "object": "order",
      "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
      "external_id": "1042",
      "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
      "email": "ada@example.com",
      "status": "paid",
      "currency": "USD",
      "subtotal": 89,
      "discount": null,
      "shipping": 5,
      "tax": 0,
      "total": 94,
      "refunded_amount": 0,
      "coupon_codes": [],
      "cart_id": null,
      "source": "api",
      "placed_at": "2026-10-08T14:32:10.000Z",
      "paid_at": "2026-10-08T14:32:11.204Z",
      "fulfilled_at": null,
      "canceled_at": null,
      "refunded_at": null,
      "attribution": {
        "email_id": "eml_3TSvDAUQi7vqxvAQ1UEVN7k4igq",
        "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
        "campaign_name": "October newsletter",
        "variant_id": null,
        "automation_id": null,
        "automation_name": null,
        "type": "click",
        "touched_at": "2026-10-08T09:41:52.000Z"
      },
      "items": [
        {
          "product_id": "8123456789",
          "variant_id": null,
          "sku": "TRS-BLU-42",
          "title": "Trail running shoe",
          "quantity": 1,
          "unit_price": 89,
          "total": 89,
          "categories": [
            "Shoes",
            "Running"
          ],
          "url": "https://shop.example.com/products/trail-running-shoe",
          "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
        }
      ],
      "metadata": {},
      "created_at": "2026-10-08T14:32:11.204Z",
      "updated_at": "2026-10-08T14:32:11.204Z"
    }
  ],
  "total_records": 1,
  "next_page_url": null,
  "previous_page_url": null
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/orders/list/

## Bestellungen gesammelt importieren — POST /orders/batch

> Senden Sie bis zu 1.000 Bestellungen in einer Anfrage, zum Beispiel Ihre Bestellhistorie. Importe werden standardmäßig keinen E-Mails zugeordnet und lösen keine Bestell-Events aus. Alpha: nur für das Emailit-Team zugänglich.

# Bestellungen gesammelt importieren

Senden Sie bis zu 1.000 Bestellungen in einer Anfrage. Importieren Sie damit Ihre Bestellhistorie, damit Kaufkennzahlen, Segmente und Produktempfehlungen vom ersten Tag an Daten haben. Jede Bestellung folgt den Regeln von [Bestellung erstellen oder aktualisieren](/de/docs/api-reference/orders/create/): Sie wird über ihre `id` erstellt oder aktualisiert, Kontakte werden erstellt, sofern `create_contact` nicht `false` ist, Warenkörbe werden konvertiert, Gutscheincodes eingelöst und Kaufkennzahlen aktualisiert. Erfordert einen API-Schlüssel mit dem Scope `full` oder `events`. Bei einem Schlüssel mit dem Scope `events` enthält die Antwort nur `object`, `id` und `external_id`.

> **Commerce ist in der Alpha:** Commerce steht nur dem Emailit-Team offen, solange wir es testen. Andere Anfragen geben `403` mit `error: "commerce_alpha"` zurück. API-Schlüssel funktionieren nur in Workspaces, die dem Emailit-Team gehören. Siehe [Wer Commerce nutzen kann](/de/docs/commerce/#who-can-use-commerce).

Standardmäßig sind die Bestellungen historisch: Sie werden keiner E-Mail zugeordnet, und Emailit löst weder `order.placed` noch `order.updated` aus, sodass sie keine Automatisierungen starten und keine Webhooks erreichen. Neue Kontakte lösen trotzdem `contact.created` aus. Bestellungen, die über diesen Endpunkt gesendet werden, haben `source` auf `import` gesetzt, mit oder ohne `historical`.

Ungültige Bestellungen werden übersprungen und in `rejected` aufgeführt; die übrigen werden gespeichert. Die Anfrage gibt trotzdem `200` zurück.

`POST /orders/batch`

## Anfrage-Body

- `orders` (object[], erforderlich): 1 bis 1.000 Bestellungen, jeweils mit den Feldern von [Bestellung erstellen oder aktualisieren](/de/docs/api-reference/orders/create/).

- `historical` (boolean): Standardwert `true`: keine Zuordnung und keine Bestell-Events. Setzen Sie den Wert auf `false`, um die Bestellungen wie einzeln gesendete Bestellungen zu behandeln: Neue Bestellungen werden E-Mails zugeordnet und lösen `order.placed` aus, aktualisierte Bestellungen lösen `order.updated` aus.

## Rückgabe

- `created` (integer): Anzahl der neuen Bestellungen.

- `updated` (integer): Anzahl der Bestellungen, die bereits gespeichert waren und aktualisiert wurden.

- `rejected` (object[]): Bestellungen, die nicht gespeichert wurden. Jeder Eintrag hat den `index` der Bestellung in Ihrem Array `orders` und `errors` mit Feldpfaden wie `orders.4.currency` als Schlüsseln. Eine Bestellung, die die Validierung bestanden hat, aber nicht gespeichert werden konnte, hat den Fehler `could not be stored` unter `orders.<index>`.

Gibt `422` zurück, wenn `orders` leer ist oder mehr als 1.000 Einträge hat.
**Anfrage** `POST /orders/batch`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/orders/batch \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "id": "981",
        "email": "ada@example.com",
        "status": "fulfilled",
        "currency": "USD",
        "placed_at": "2026-03-14T10:12:00Z",
        "items": [{ "product_id": "8123456789", "quantity": 1, "price": 89 }]
      },
      {
        "id": "982",
        "email": "grace@example.com",
        "status": "fulfilled",
        "currency": "usd dollars",
        "total": 18,
        "placed_at": "2026-03-15T16:40:00Z"
      }
    ]
  }'
```

**200**

```json
{
  "created": 1,
  "updated": 0,
  "rejected": [
    {
      "index": 1,
      "errors": {
        "orders.1.currency": [
          "must be a three-letter ISO 4217 code, e.g. USD"
        ]
      }
    }
  ]
}
```

**422**

```json
{
  "message": "Validation failed. orders: Send 1 to 1000 orders.",
  "errors": {
    "orders": [
      "Send 1 to 1000 orders."
    ]
  }
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/orders/batch/

## Bestellung löschen — DELETE /orders/{id}

> Löschen Sie eine Bestellung und ihre Artikel und berechnen Sie die Kaufkennzahlen des Käufers neu. Alpha: nur für das Emailit-Team zugänglich.

# Bestellung löschen

Löscht eine Bestellung und ihre Artikel. Die Kaufkennzahlen des Käufers werden ohne sie neu berechnet, und ihr Umsatz zählt in Berichten nicht mehr. Von ihr eingelöste Gutscheincodes bleiben eingelöst, und konvertierte Warenkörbe bleiben konvertiert. Es wird kein Event ausgelöst. Um die Bestellung zu behalten, ihren Umsatz aber nicht mehr zu zählen, setzen Sie stattdessen ihren Status mit [Bestellung aktualisieren](/de/docs/api-reference/orders/update/) auf `canceled`. Erfordert einen API-Schlüssel mit dem Scope `full`.

> **Commerce ist in der Alpha:** Commerce steht nur dem Emailit-Team offen, solange wir es testen. Andere Anfragen geben `403` mit `error: "commerce_alpha"` zurück. API-Schlüssel funktionieren nur in Workspaces, die dem Emailit-Team gehören. Siehe [Wer Commerce nutzen kann](/de/docs/commerce/#who-can-use-commerce).

`DELETE /orders/{id}`

## Pfadparameter

- `id` (string, erforderlich): Die Bestell-ID (`ord_...`) oder die Bestell-ID in Ihrem Shop.

**Anfrage** `DELETE /orders/{id}`

**cURL**

```bash
curl -X DELETE https://api.emailit.com/v2/orders/ord_3aMEK4No62Zw8S1fcHNznAnnbfp \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "object": "order",
  "id": "ord_3aMEK4No62Zw8S1fcHNznAnnbfp",
  "deleted": true
}
```

**404**

```json
{
  "error": "Order not found",
  "message": "Order not found."
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/orders/delete/