Bestellungen

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

Basis-URLhttps://api.emailit.com/v2Authentifizierung Fehler Rate Limits

POST/orders
GET/orders/{id}
POST/orders/{id}
GET/orders
POST/orders/batch
DEL/orders/{id}

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.

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. Siehe Wie Bestellungen E-Mails zugeordnet werden.
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 aus, das Webhooks und Automatisierungen empfangen.

Wenn Sie eine bereits gespeicherte Bestellung senden, wird sie aktualisiert und 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 verwenden.

Um frühere Bestellungen zu importieren, ohne sie E-Mails zuzuordnen oder Automatisierungen zu starten, verwenden Sie Bestellungen gesammelt importieren.

POST/orders

Anfrage-Body

idstring | numberErforderlich

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.

emailstring

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_idstring

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

first_namestring

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

last_namestring

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

statusstring

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.

currencystring

Dreistelliger Code nach ISO 4217. Standardmäßig gilt die Währung des Workspaces aus den Commerce-Einstellungen. Beträge werden nie umgerechnet: Berichte gruppieren den Umsatz nach Währung.

totalnumber | 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.

subtotalnumber | string

Betrag vor Rabatt, Versandkosten und Steuern. Standardwert bei Bestellungen mit Artikeln: die Summe der Positionsbeträge.

discountnumber | string

Rabattbetrag als positive Zahl.

shippingnumber | string

Versandkosten.

taxnumber | string

Steuerbetrag.

refunded_amountnumber | string

Erstatteter Betrag. Standardwert 0 oder total, wenn status refunded ist. Der Umsatz ist total abzüglich refunded_amount.

coupon_codesstring[]

Bis zu 20 Gutschein- oder Rabattcodes, die in der Bestellung verwendet wurden. Ein Code, der ohne Beachtung der Groß-/Kleinschreibung einem Gutscheincode im Workspace entspricht, wird als durch diese Bestellung eingelöst markiert. coupon_code und discount_codes werden ebenfalls akzeptiert.

cart_idstring

Die Warenkorb- oder Checkout-ID in Ihrem Shop, aus der die Bestellung stammt. Der Warenkorb mit dieser ID wird converted.

placed_atstring | 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.

itemsobject[]

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. 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.

metadataobject

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_contactboolean

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_marketingboolean

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_idstring

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_idstring

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, wenn die Bestellung neu ist, oder 200 OK, wenn eine bestehende Bestellung aktualisiert wurde. Gibt 422 zurück, wenn ein Feld ungültig ist.

POST/orders

Terminal

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"
  }'

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"
}

JSON

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

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.

GET/orders/{id}

Pfadparameter

idstringErforderlich

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

objectstring

Immer order.

idstring

Emailit-Bestell-ID (ord_...).

external_idstring

Die Bestell-ID in Ihrem Shop: die id, die Sie gesendet haben.

contact_idstring | null

Der Kontakt des Käufers (con_...) oder null, wenn die Bestellung mit keinem Kontakt verknüpft ist.

emailstring | null

Die E-Mail-Adresse des Käufers, in Kleinbuchstaben.

statusstring

placed, paid, fulfilled, canceled oder refunded.

currencystring

Dreistelliger Code nach ISO 4217 für die Beträge.

subtotalnumber | null

Summe der Artikel vor Rabatt, Versandkosten und Steuern.

discountnumber | null

Rabattbetrag.

shippingnumber | null

Versandkosten.

taxnumber | null

Steuerbetrag.

totalnumber

Bestellsumme. Der Umsatz in Berichten ist total abzüglich refunded_amount, und stornierte Bestellungen zählen nicht.

refunded_amountnumber

Bisher erstatteter Betrag. 0, wenn nichts erstattet wurde.

coupon_codesstring[]

In der Bestellung verwendete Gutschein- oder Rabattcodes.

cart_idstring | null

Die Warenkorb- oder Checkout-ID in Ihrem Shop, aus der die Bestellung stammt.

sourcestring

Wie die Bestellung zu Emailit gelangt ist: api, js (das Tracking-Skript) oder import (Sammelimport).

placed_atstring

Zeitpunkt, zu dem die Bestellung aufgegeben wurde, im Format ISO 8601 in UTC.

paid_at, fulfilled_at, canceled_at, refunded_atstring | 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.

attributionobject | 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.

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.

itemsobject[]

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

metadataobject

Ihre eigenen Schlüssel-Wert-Daten.

created_at, updated_atstring

Zeitpunkt, zu dem Emailit die Bestellung gespeichert hat, und Zeitpunkt ihrer letzten Änderung, im Format ISO 8601 in UTC.

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"
}

JSON

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

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 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.

POST/orders/{id}

Pfadparameter

idstringErforderlich

Die Bestell-ID (ord_...) oder die Bestell-ID in Ihrem Shop.

Anfrage-Body

Senden Sie mindestens eines dieser Felder.

statusstring

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_amountnumber | 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.

metadataobject

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. Gibt 404 zurück, wenn keine Bestellung zu id passt, und 422, wenn der Body leer oder ein Feld ungültig ist.

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"
}

JSON

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

JSON

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

Bestellungen auflisten

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

GET/orders

Query-Parameter

pageinteger

Seitennummer für die Paginierung (Minimum: 1, Standardwert: 1).

limitinteger

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

searchstring

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

contact_idstring

Nur Bestellungen dieses Kontakts (con_...).

emailstring

Nur Bestellungen mit dieser E-Mail-Adresse des Käufers, ohne Beachtung der Groß-/Kleinschreibung.

statusstring

Nur Bestellungen mit diesem Status: placed, paid, fulfilled, canceled oder refunded.

campaign_idstring

Nur Bestellungen, die dieser Kampagne zugeordnet sind (cmp_...).

automation_idstring

Nur Bestellungen, die dieser Automatisierung zugeordnet sind (aut_...).

attributedboolean

true für Bestellungen, die einer E-Mail zugeordnet sind, false für Bestellungen ohne Zuordnung.

fromstring

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.

tostring

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.

matchstring

all (Standardwert) verlangt, dass jeder Filter key.condition zutrifft. Bei or genügt einer davon. Siehe Filtern und Sortieren.

sortstring

Sortierschlüssel: placed_at (Standardwert), total oder created_at.

orderstring

Sortierrichtung: asc oder desc (Standardwert).

Filter

Listenfilter sind Query-Parameter der Form key.condition=value auf einer einzigen Ebene. match, order, direction und die Bedingungen pro Typ finden Sie unter Filtern und Sortieren.

Filterschlüssel

Schlüssel	Typ	Bedingungen	Hinweise
`external_id`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`email`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`status`	enum	exact, not_exact	Werte: `placed`, `paid`, `fulfilled`, `canceled`, `refunded`
`currency`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`total`	number	exact, not_exact, gt, gte, lt, lte, empty, not_empty
`source`	enum	exact, not_exact	Werte: `api`, `js`, `import`, `dashboard`
`attribution_type`	enum	exact, not_exact	Werte: `click`, `open`
`placed_at`	date	exact, before, after, empty, not_empty
`created_at`	date	exact, before, after, empty, not_empty

Sortierschlüssel

Dieser Endpunkt sortiert mit sort, gesetzt auf einen dieser Schlüssel, und order, gesetzt auf asc oder desc (order=<key> gibt hier 400 zurück): placed_at, total, created_at

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 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.

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
}

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

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

ordersobject[]Erforderlich

1 bis 1.000 Bestellungen, jeweils mit den Feldern von Bestellung erstellen oder aktualisieren.

historicalboolean

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

createdinteger

Anzahl der neuen Bestellungen.

updatedinteger

Anzahl der Bestellungen, die bereits gespeichert waren und aktualisiert wurden.

rejectedobject[]

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.

POST/orders/batch

Terminal

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"
      }
    ]
  }'

JSON

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

JSON

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

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 auf canceled. Erfordert einen API-Schlüssel mit dem Scope full.

DELETE/orders/{id}

Pfadparameter

idstringErforderlich

Die Bestell-ID (ord_...) oder die Bestell-ID in Ihrem Shop.

JSON

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

JSON

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