Objednávky

Posílejte objednávky ze svého obchodu, aby se tržby připsaly e-mailům a vznikly nákupní profily.

Základní URLhttps://api.emailit.com/v2Autentizace Chyby Limity rychlosti

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

Vytvoření nebo úprava objednávky

Pošlete objednávku z backendu svého obchodu. Klíčem objednávky je její id ve vašem obchodě: když stejné id pošlete znovu, uložená objednávka se místo toho upraví. Vyžaduje API klíč s oprávněním full, nebo events. S klíčem s oprávněním events obsahuje odpověď jen object, id a external_id.

Když se objednávka uloží poprvé, Emailit:

ji připíše e-mailu z kampaně nebo automatizace, na který kupující naposledy klikl v okně pro proklik před placed_at, nebo, pokud neklikl, e-mailu, který naposledy otevřel v okně pro otevření. Okna jsou v nastavení E-commerce. Viz Jak se objednávky připisují e-mailům.
ji propojí s kontaktem kupujícího a v případě potřeby kontakt vytvoří (viz create_contact).
označí košík uvedený v cart_id jako převedený na objednávku, stejně jako ostatní otevřené košíky kupujícího, které se naposledy změnily před objednávkou.
označí odpovídající slevové kódy jako uplatněné.
aktualizuje nákupní metriky kontaktu.
vyvolá událost order.placed, kterou dostávají webhooky a automatizace.

Odeslání objednávky, která už je uložená, ji upraví a vyvolá order.updated, při změně stavu s previous_status. Přiřazení tržeb se nemění. Změní se jen pole, která pošlete: status, placed_at, currency, částky, coupon_codes, cart_id a items si ponechají uložené hodnoty, když je vynecháte, metadata se sloučí s uloženým objektem a total není povinné. Odesláním items se nahradí všechny položky. Pokud chcete změnit jen stav nebo vrácení peněz, můžete použít také endpoint Úprava objednávky.

Pokud chcete naimportovat starší objednávky, aniž by se připsaly e-mailům nebo spustily automatizace, použijte Hromadný import objednávek.

POST/orders

Tělo požadavku

idstring | numberPovinné

ID objednávky ve vašem obchodě, nejvýše 255 znaků. Čísla se ukládají jako řetězce. Ukládá se jako external_id. Můžete ho poslat také jako external_id nebo order_id.

emailstring

Kontaktní e-mail kupujícího. Ukládá se malými písmeny. Emailit podle ní najde kontakt a připíše objednávku e-mailu odeslanému na tuto adresu. Přijímá se také customer.email.

contact_idstring

Kontakt kupujícího (con_...). Pokud žádný kontakt nemá toto ID, Emailit kontakt dohledá podle email.

first_namestring

Křestní jméno kupujícího, nejvýše 191 znaků. Použije se, když Emailit kontakt vytváří. Přijímá se také customer.first_name.

last_namestring

Příjmení kupujícího, nejvýše 191 znaků. Použije se, když Emailit kontakt vytváří. Přijímá se také customer.last_name.

statusstring

placed (výchozí hodnota), paid, fulfilled, canceled nebo refunded. Když má objednávka poprvé stav paid, fulfilled, canceled nebo refunded, Emailit nastaví odpovídající paid_at, fulfilled_at, canceled_at nebo refunded_at na aktuální čas. Zrušené objednávky se do tržeb nepočítají.

currencystring

Třípísmenný kód ISO 4217. Výchozí hodnota je měna workspace v nastavení E-commerce. Částky se nikdy nepřevádějí: reporty seskupují tržby podle měny.

totalnumber | string

Celková částka objednávky. Povinná u nové objednávky bez položek. Bez ní Emailit spočítá součet částek položek minus discount plus shipping a tax, nikdy méně než 0.

Částky jsou čísla nebo číselné řetězce, nesmí být záporné a ukládají se s nejvýše 4 desetinnými místy.

subtotalnumber | string

Částka před slevou, dopravou a daní. Pokud objednávka obsahuje položky, výchozí hodnota je součet jejich částek.

discountnumber | string

Výše slevy jako kladné číslo.

shippingnumber | string

Cena dopravy.

taxnumber | string

Výše daně.

refunded_amountnumber | string

Vrácená částka. Výchozí hodnota je 0, nebo total, když je status refunded. Tržby jsou total minus refunded_amount.

coupon_codesstring[]

Až 20 kuponů nebo slevových kódů použitých v objednávce. Kód, který bez ohledu na velikost písmen odpovídá kódu kuponu ve workspace, se označí jako uplatněný touto objednávkou. Přijímají se také coupon_code a discount_codes.

cart_idstring

ID košíku nebo pokladny ve vašem obchodě, ze kterého objednávka vznikla. Košík s tímto ID přejde do stavu converted.

placed_atstring | number

Kdy byla objednávka zadána: datum a čas ve formátu ISO 8601, nebo unixové časové razítko v sekundách (fungují i milisekundy). Výchozí hodnota je aktuální čas. Nesmí být víc než 24 hodin v budoucnosti. Přijímá se také created_at.

itemsobject[]

Až 250 položek objednávky. Přijímá se také line_items. Každá položka má:

product_id (string nebo number): ID produktu ve vašem obchodě. Položky bez title, url, image_url nebo categories je převezmou z katalogu. Přijímá se také id.
variant_id, sku (string): nejvýše 255 znaků.
title (string): nejvýše 500 znaků. Povinné, když položka nemá product_id ani sku. Přijímá se také name.
quantity (integer): 1 nebo více. Výchozí hodnota je 1.
price (number nebo string): jednotková cena. Výchozí hodnota je 0. Přijímá se také unit_price.
total (number nebo string): celková částka položky. Výchozí hodnota je price krát quantity.
categories (string[]): až 50 názvů kategorií.
url, image_url (string): URL s http nebo https.

metadataobject

Vaše vlastní data ve tvaru dvojic klíč–hodnota, nejvýše 16 KB jako JSON. Při úpravách se odeslané klíče sloučí s uloženým objektem.

create_contactboolean

Výchozí hodnota true: když contact_id ani email neodpovídá žádnému kontaktu, Emailit vytvoří kontakt z email, first_name a last_name a vyvolá contact.created. Nový kontakt není přihlášený k žádnému seznamu kontaktů, takže ho kampaně nezasáhnou. Nastavte na false, pokud se kontakt nikdy vytvářet nemá: objednávka se pak propojí jen s kontaktem, který už existuje.

accepts_marketingboolean

Nastavte na true spolu s audience_id, když kupující souhlasil se zasíláním marketingových sdělení. Emailit pak kontakt přihlásí k tomuto seznamu kontaktů, pokud v něm už není. Výchozí hodnota je false.

audience_idstring

Seznam kontaktů (aud_...), ke kterému se kupující přihlásí, když je accepts_marketing true. Pokud seznam neexistuje nebo je dosažený limit odběratelů vašeho tarifu, objednávka se přesto uloží a kontakt se nepřihlásí.

email_idstring

Kampaňový e-mail (eml_...), ze kterého kupující přišel, pokud to váš obchod sleduje. Použije se jen u nových objednávek a čtou se jen ID začínající na eml_. Objednávka se tomuto e-mailu připíše, když jde o e-mail z kampaně tohoto workspace a buď má proklik v okně pro proklik před objednávkou, nebo byl v tomto okně odeslán. Jinak Emailit objednávku připíše obvyklým způsobem. Přijímá se také attribution.email_id.

Odpověď

201 Created s objektem objednávky, když je objednávka nová, nebo 200 OK, když se upravila existující objednávka. Pokud je některé pole neplatné, vrací 422.

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

Načtení objednávky

Načte objednávku podle jejího ID v Emailitu nebo podle ID objednávky ve vašem obchodě, s jejími položkami a přiřazením tržeb. Vyžaduje API klíč s oprávněním full.

GET/orders/{id}

Parametry v cestě

idstringPovinné

ID objednávky (ord_...), nebo ID objednávky ve vašem obchodě (external_id). ID z obchodu, která obsahují speciální znaky, zakódujte pro URL.

Objekt objednávky

objectstring

Vždy order.

idstring

ID objednávky v Emailitu (ord_...).

external_idstring

ID objednávky ve vašem obchodě: id, které jste poslali.

contact_idstring | null

Kontakt kupujícího (con_...), nebo null, když objednávka není propojená s žádným kontaktem.

emailstring | null

Kontaktní e-mail kupujícího, malými písmeny.

statusstring

placed, paid, fulfilled, canceled nebo refunded.

currencystring

Třípísmenný kód ISO 4217 měny částek.

subtotalnumber | null

Součet položek před slevou, dopravou a daní.

discountnumber | null

Výše slevy.

shippingnumber | null

Cena dopravy.

taxnumber | null

Výše daně.

totalnumber

Celková částka objednávky. Tržby v reportech jsou total minus refunded_amount a zrušené objednávky se nepočítají.

refunded_amountnumber

Dosud vrácená částka. 0, když se nic nevrátilo.

coupon_codesstring[]

Kupony nebo slevové kódy použité v objednávce.

cart_idstring | null

ID košíku nebo pokladny ve vašem obchodě, ze kterého objednávka vznikla.

sourcestring

Jak se objednávka dostala do Emailitu: api, js (měřicí skript) nebo import (hromadný import).

placed_atstring

Kdy byla objednávka zadána, ve formátu ISO 8601 v UTC.

paid_at, fulfilled_at, canceled_at, refunded_atstring | null

Kdy Emailit poprvé uložil objednávku s daným stavem. Nastaví se jednou a při další změně stavu se nevymaže.

attributionobject | null

Kampaňový nebo automatizační e-mail, kterému je objednávka připsaná, nebo null. Nastaví se jednou, při prvním uložení objednávky. Viz Jak se objednávky připisují e-mailům.

email_id (string): e-mail, kterému je objednávka připsaná.
campaign_id, campaign_name (string nebo null): jeho kampaň.
variant_id (string nebo null): verze A/B testu (cvr_...), kterou kupující dostal.
automation_id, automation_name (string nebo null): jeho automatizace.
type (string): click, nebo open.
touched_at (string nebo null): kdy proklik nebo otevření nastalo.

itemsobject[]

Položky objednávky. Každá má product_id (ID produktu ve vašem obchodě), variant_id, sku, title, quantity, unit_price, total, categories, url a image_url.

metadataobject

Vaše vlastní data ve tvaru dvojic klíč–hodnota.

created_at, updated_atstring

Kdy Emailit objednávku uložil a kdy se naposledy změnila, ve formátu ISO 8601 v 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."
}

Úprava objednávky

Změní stav uložené objednávky, zaznamená vrácení peněz nebo přidá metadata. Všechno ostatní zůstane, jak je, včetně položek a přiřazení tržeb. Nákupní metriky kupujícího se přepočítají a Emailit vyvolá order.updated, při změně stavu s previous_status objednávky. Vyžaduje API klíč s oprávněním full, nebo events. S klíčem s oprávněním events obsahuje odpověď jen object, id a external_id.

POST/orders/{id}

Parametry v cestě

idstringPovinné

ID objednávky (ord_...), nebo ID objednávky ve vašem obchodě.

Tělo požadavku

Pošlete aspoň jedno z těchto polí.

statusstring

placed, paid, fulfilled, canceled nebo refunded. Když objednávka poprvé dostane stav paid, fulfilled, canceled nebo refunded, odpovídající paid_at, fulfilled_at, canceled_at nebo refunded_at se nastaví na aktuální čas. Zrušené objednávky se do tržeb nepočítají.

refunded_amountnumber | string

Celková dosud vrácená částka, ne částka tohoto vrácení. Nesmí být záporná. Tržby jsou total minus refunded_amount. Pokud nastavíte status na refunded bez refunded_amount a dřív se nic nevrátilo, za vrácenou se považuje celá částka total.

metadataobject

Klíče, které se sloučí s metadaty objednávky. Nejvýše 16 KB jako JSON.

Odpověď

200 OK s upraveným objektem objednávky. Pokud parametru id neodpovídá žádná objednávka, vrací 404, a pokud je tělo prázdné nebo je některé pole neplatné, vrací 422.

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

Výpis objednávek

Vypíše objednávky s jejich položkami, naposledy zadané jako první. Vyžaduje API klíč s oprávněním full.

GET/orders

Parametry dotazu

pageinteger

Číslo stránky pro stránkování (nejméně 1, výchozí hodnota 1).

limitinteger

Počet objednávek, které se vrátí (nejméně 1, nejvýše 100, výchozí hodnota 25).

searchstring

Hledá v ID objednávky ve vašem obchodě nebo v e-mailové adrese kupujícího bez ohledu na velikost písmen.

contact_idstring

Jen objednávky tohoto kontaktu (con_...).

emailstring

Jen objednávky s touto e-mailovou adresou kupujícího, bez ohledu na velikost písmen.

statusstring

Jen objednávky v tomto stavu: placed, paid, fulfilled, canceled nebo refunded.

campaign_idstring

Jen objednávky připsané této kampani (cmp_...).

automation_idstring

Jen objednávky připsané této automatizaci (aut_...).

attributedboolean

true pro objednávky připsané nějakému e-mailu, false pro objednávky, které připsané nejsou.

fromstring

Jen objednávky zadané v tento čas nebo později. Datum, nebo datum a čas ve formátu ISO 8601; cokoli jiného vrací 422.

tostring

Jen objednávky zadané v tento čas nebo dříve. Datum, nebo datum a čas ve formátu ISO 8601; cokoli jiného vrací 422.

matchstring

all (výchozí) vyžaduje shodu všech filtrů key.condition. U or stačí shoda kteréhokoli z nich. Viz Filtrování a řazení.

sortstring

Klíč řazení: placed_at (výchozí), total nebo created_at.

orderstring

Směr řazení: asc, nebo desc (výchozí).

Filtry

Filtry výpisů jsou jedna úroveň parametrů dotazu ve tvaru key.condition=value. Parametry match, order a direction a seznam podmínek pro každý typ najdete na stránce Filtrování.

Klíče filtrů

Klíč	Typ	Podmínky	Poznámky
`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	Hodnoty: `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	Hodnoty: `api`, `js`, `import`, `dashboard`
`attribution_type`	enum	exact, not_exact	Hodnoty: `click`, `open`
`placed_at`	date	exact, before, after, empty, not_empty
`created_at`	date	exact, before, after, empty, not_empty

Klíče řazení

Tento endpoint řadí podle parametru sort s jedním z těchto klíčů a parametru order s hodnotou asc, nebo desc (order=<key> tu vrací 400): placed_at, total, created_at

U tohoto endpointu přijímá order jen asc, nebo desc. Klíč řazení předejte v sort, například sort=total&order=desc.

Odpověď

Stránka objektů objednávek v poli data a k tomu total_records, next_page_url a previous_page_url. URL stránek nesou jen page a limit, takže když na ně přejdete, přidejte znovu své vyhledávání a filtry.

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
}

Hromadný import objednávek

Pošle až 1 000 objednávek v jednom požadavku. Použijte ho k importu historie objednávek, aby nákupní metriky, segmenty a doporučení produktů měly data od prvního dne. Každá objednávka se řídí pravidly endpointu Vytvoření nebo úprava objednávky: vytvoří se, nebo upraví podle svého id, kontakty se vytvoří, pokud create_contact není false, košíky se převedou na objednávku, slevové kódy se uplatní a nákupní metriky se aktualizují. Vyžaduje API klíč s oprávněním full, nebo events. S klíčem s oprávněním events obsahuje odpověď jen object, id a external_id.

Ve výchozím stavu jsou objednávky historické: nepřipíšou se žádnému e-mailu a Emailit nevyvolá order.placed ani order.updated, takže nespouštějí automatizace a nedostanou se do webhooků. Nové kontakty přesto vyvolají contact.created. Objednávky odeslané tímto endpointem mají source nastavené na import, s historical i bez něj.

Neplatné objednávky se přeskočí a vypíšou v rejected; ostatní se uloží. Požadavek přesto vrátí 200.

POST/orders/batch

Tělo požadavku

ordersobject[]Povinné

1 až 1 000 objednávek, každá s poli endpointu Vytvoření nebo úprava objednávky.

historicalboolean

Výchozí hodnota true: žádné přiřazení tržeb a žádné události objednávek. Nastavte na false, pokud se objednávky mají zpracovat jako objednávky posílané jednotlivě: nové objednávky se připíšou e-mailům a vyvolají order.placed, upravené objednávky vyvolají order.updated.

Odpověď

createdinteger

Počet nových objednávek.

updatedinteger

Počet objednávek, které už byly uložené a upravily se.

rejectedobject[]

Objednávky, které se neuložily. Každá položka má index objednávky ve vašem poli orders a errors s klíči podle cesty k poli, například orders.4.currency. Objednávka, která prošla validací, ale nepodařilo se ji uložit, má pod orders.<index> chybu could not be stored.

Pokud je orders prázdné nebo má víc než 1 000 položek, vrací 422.

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

Smazání objednávky

Smaže objednávku i s jejími položkami. Nákupní metriky kupujícího se přepočítají bez ní a její tržby se v reportech přestanou počítat. Slevové kódy, které uplatnila, zůstanou uplatněné a košíky převedené na objednávku zůstanou převedené. Nevyvolá se žádná událost. Pokud chcete objednávku zachovat, ale přestat počítat její tržby, nastavte jí místo toho endpointem Úprava objednávky stav canceled. Vyžaduje API klíč s oprávněním full.

DELETE/orders/{id}

Parametry v cestě

idstringPovinné

ID objednávky (ord_...), nebo ID objednávky ve vašem obchodě.

JSON

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

JSON

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