# Objednávky API

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

Základní URL: `https://api.emailit.com/v2`. Autentizujte se hlavičkou `Authorization: Bearer <API key>`.

## Vytvoření nebo úprava objednávky — POST /orders

> Pošlete objednávku ze svého obchodu. Emailit nové objednávky připisuje e-mailu, na který kupující naposledy klikl nebo který naposledy otevřel, aktualizuje nákupní profil kupujícího a vyvolá order.placed. Alfaverze: otevřená jen týmu Emailitu.

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

> **E-commerce je v alfaverzi:** Dokud E-commerce testujeme, je otevřené jen týmu Emailitu. Ostatní požadavky vracejí `403` s `error: "commerce_alpha"`. API klíče fungují jen ve workspace, které vlastní tým Emailitu. Viz [Kdo může E-commerce používat](/cs/docs/commerce/#who-can-use-commerce).

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](/cs/docs/api-reference/commerce/get-settings/). Viz [Jak se objednávky připisují e-mailům](/cs/docs/commerce/#how-orders-are-credited-to-emails).
- 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`](/cs/docs/webhooks/events/order/placed/), kterou dostávají webhooky a automatizace.

Odeslání objednávky, která už je uložená, ji upraví a vyvolá [`order.updated`](/cs/docs/webhooks/events/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](/cs/docs/api-reference/orders/update/).

Pokud chcete naimportovat starší objednávky, aniž by se připsaly e-mailům nebo spustily automatizace, použijte [Hromadný import objednávek](/cs/docs/api-reference/orders/batch/).

`POST /orders`

## Tělo požadavku

- `id` (string | number, povinné): 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`.

- `email` (string): 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_id` (string): Kontakt kupujícího (`con_...`). Pokud žádný kontakt nemá toto ID, Emailit kontakt dohledá podle `email`.

- `first_name` (string): 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_name` (string): Příjmení kupujícího, nejvýše 191 znaků. Použije se, když Emailit kontakt vytváří. Přijímá se také `customer.last_name`.

- `status` (string): `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í.

- `currency` (string): Třípísmenný kód ISO 4217. Výchozí hodnota je měna workspace v [nastavení E-commerce](/cs/docs/api-reference/commerce/get-settings/). Částky se nikdy nepřevádějí: reporty seskupují tržby podle měny.

- `total` (number | 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.

- `subtotal` (number | string): Částka před slevou, dopravou a daní. Pokud objednávka obsahuje položky, výchozí hodnota je součet jejich částek.

- `discount` (number | string): Výše slevy jako kladné číslo.

- `shipping` (number | string): Cena dopravy.

- `tax` (number | string): Výše daně.

- `refunded_amount` (number | string): Vrácená částka. Výchozí hodnota je `0`, nebo `total`, když je `status` `refunded`. Tržby jsou `total` minus `refunded_amount`.

- `coupon_codes` (string[]): 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](/cs/docs/api-reference/coupons/list-codes/) ve workspace, se označí jako uplatněný touto objednávkou. Přijímají se také `coupon_code` a `discount_codes`.

- `cart_id` (string): ID košíku nebo pokladny ve vašem obchodě, ze kterého objednávka vznikla. [Košík](/cs/docs/api-reference/carts/upsert/) s tímto ID přejde do stavu `converted`.

- `placed_at` (string | 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`.

- `items` (object[]): 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](/cs/docs/api-reference/products/create/). 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`.

- `metadata` (object): 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_contact` (boolean): 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_marketing` (boolean): 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_id` (string): 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_id` (string): 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](/cs/docs/api-reference/orders/get/), když je objednávka nová, nebo `200 OK`, když se upravila existující objednávka. Pokud je některé pole neplatné, vrací `422`.
**Požadavek** `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"
    ]
  }
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/orders/create/

## Načtení objednávky — GET /orders/{id}

> Načtěte objednávku s jejími položkami a s e-mailem z kampaně nebo automatizace, kterému je připsaná. Alfaverze: otevřená jen týmu Emailitu.

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

> **E-commerce je v alfaverzi:** Dokud E-commerce testujeme, je otevřené jen týmu Emailitu. Ostatní požadavky vracejí `403` s `error: "commerce_alpha"`. API klíče fungují jen ve workspace, které vlastní tým Emailitu. Viz [Kdo může E-commerce používat](/cs/docs/commerce/#who-can-use-commerce).

`GET /orders/{id}`

## Parametry v cestě

- `id` (string, povinné): 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

- `object` (string): Vždy `order`.

- `id` (string): ID objednávky v Emailitu (`ord_...`).

- `external_id` (string): ID objednávky ve vašem obchodě: `id`, které jste poslali.

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

- `email` (string | null): Kontaktní e-mail kupujícího, malými písmeny.

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

- `currency` (string): Třípísmenný kód ISO 4217 měny částek.

- `subtotal` (number | null): Součet položek před slevou, dopravou a daní.

- `discount` (number | null): Výše slevy.

- `shipping` (number | null): Cena dopravy.

- `tax` (number | null): Výše daně.

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

- `refunded_amount` (number): Dosud vrácená částka. `0`, když se nic nevrátilo.

- `coupon_codes` (string[]): Kupony nebo slevové kódy použité v objednávce.

- `cart_id` (string | null): ID košíku nebo pokladny ve vašem obchodě, ze kterého objednávka vznikla.

- `source` (string): Jak se objednávka dostala do Emailitu: `api`, `js` (měřicí skript) nebo `import` ([hromadný import](/cs/docs/api-reference/orders/batch/)).

- `placed_at` (string): Kdy byla objednávka zadána, ve formátu ISO 8601 v UTC.

- `paid_at, fulfilled_at, canceled_at, refunded_at` (string | 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.

- `attribution` (object | 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](/cs/docs/commerce/#how-orders-are-credited-to-emails). - `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.

- `items` (object[]): 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`.

- `metadata` (object): Vaše vlastní data ve tvaru dvojic klíč–hodnota.

- `created_at, updated_at` (string): Kdy Emailit objednávku uložil a kdy se naposledy změnila, ve formátu ISO 8601 v UTC.

**Požadavek** `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."
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/orders/get/

## Úprava objednávky — POST /orders/{id}

> Změňte stav objednávky, zaznamenejte vrácení peněz nebo přidejte metadata, aniž byste znovu posílali celou objednávku. Alfaverze: otevřená jen týmu Emailitu.

# Ú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`](/cs/docs/webhooks/events/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`.

> **E-commerce je v alfaverzi:** Dokud E-commerce testujeme, je otevřené jen týmu Emailitu. Ostatní požadavky vracejí `403` s `error: "commerce_alpha"`. API klíče fungují jen ve workspace, které vlastní tým Emailitu. Viz [Kdo může E-commerce používat](/cs/docs/commerce/#who-can-use-commerce).

`POST /orders/{id}`

## Parametry v cestě

- `id` (string, povinné): ID objednávky (`ord_...`), nebo ID objednávky ve vašem obchodě.

## Tělo požadavku

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

- `status` (string): `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_amount` (number | 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`.

- `metadata` (object): Klíče, které se sloučí s metadaty objednávky. Nejvýše 16 KB jako JSON.

## Odpověď

`200 OK` s upraveným [objektem objednávky](/cs/docs/api-reference/orders/get/). 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`.
**Požadavek** `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"
    ]
  }
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/orders/update/

## Výpis objednávek — GET /orders

> Vypište objednávky od nejnovějších, filtrované podle kupujícího, stavu, časového rozmezí nebo kampaně či automatizace, které jsou připsané. Alfaverze: otevřená jen týmu Emailitu.

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

> **E-commerce je v alfaverzi:** Dokud E-commerce testujeme, je otevřené jen týmu Emailitu. Ostatní požadavky vracejí `403` s `error: "commerce_alpha"`. API klíče fungují jen ve workspace, které vlastní tým Emailitu. Viz [Kdo může E-commerce používat](/cs/docs/commerce/#who-can-use-commerce).

`GET /orders`

## Parametry dotazu

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

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

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

- `contact_id` (string): Jen objednávky tohoto kontaktu (`con_...`).

- `email` (string): Jen objednávky s touto e-mailovou adresou kupujícího, bez ohledu na velikost písmen.

- `status` (string): Jen objednávky v tomto stavu: `placed`, `paid`, `fulfilled`, `canceled` nebo `refunded`.

- `campaign_id` (string): Jen objednávky připsané této kampani (`cmp_...`).

- `automation_id` (string): Jen objednávky připsané této automatizaci (`aut_...`).

- `attributed` (boolean): `true` pro objednávky připsané nějakému e-mailu, `false` pro objednávky, které připsané nejsou.

- `from` (string): 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`.

- `to` (string): 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`.

- `match` (string): `all` (výchozí) vyžaduje shodu všech filtrů `key.condition`. U `or` stačí shoda kteréhokoli z nich. Viz [Filtrování a řazení](/cs/docs/api-reference/filtering/).

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

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

## Filtry

Klíče filtrů a řazení: viz [Filtrování](https://emailit.com/cs/docs/api-reference/filtering/).

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](/cs/docs/api-reference/orders/get/) 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.
**Požadavek** `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
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/orders/list/

## Hromadný import objednávek — POST /orders/batch

> Pošlete až 1 000 objednávek v jednom požadavku, například historii objednávek. Importy ve výchozím stavu nepřipisují objednávky e-mailům a nevyvolávají události objednávek. Alfaverze: otevřená jen týmu Emailitu.

# 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](/cs/docs/api-reference/orders/create/): 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`.

> **E-commerce je v alfaverzi:** Dokud E-commerce testujeme, je otevřené jen týmu Emailitu. Ostatní požadavky vracejí `403` s `error: "commerce_alpha"`. API klíče fungují jen ve workspace, které vlastní tým Emailitu. Viz [Kdo může E-commerce používat](/cs/docs/commerce/#who-can-use-commerce).

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

- `orders` (object[], povinné): 1 až 1 000 objednávek, každá s poli endpointu [Vytvoření nebo úprava objednávky](/cs/docs/api-reference/orders/create/).

- `historical` (boolean): 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ěď

- `created` (integer): Počet nových objednávek.

- `updated` (integer): Počet objednávek, které už byly uložené a upravily se.

- `rejected` (object[]): 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`.
**Požadavek** `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."
    ]
  }
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/orders/batch/

## Smazání objednávky — DELETE /orders/{id}

> Smažte objednávku i s jejími položkami a přepočítejte nákupní metriky kupujícího. Alfaverze: otevřená jen týmu Emailitu.

# 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](/cs/docs/api-reference/orders/update/) stav `canceled`. Vyžaduje API klíč s oprávněním `full`.

> **E-commerce je v alfaverzi:** Dokud E-commerce testujeme, je otevřené jen týmu Emailitu. Ostatní požadavky vracejí `403` s `error: "commerce_alpha"`. API klíče fungují jen ve workspace, které vlastní tým Emailitu. Viz [Kdo může E-commerce používat](/cs/docs/commerce/#who-can-use-commerce).

`DELETE /orders/{id}`

## Parametry v cestě

- `id` (string, povinné): ID objednávky (`ord_...`), nebo ID objednávky ve vašem obchodě.

**Požadavek** `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."
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/orders/delete/