# E-commerce API

> Nastavení e-commerce, přehled tržeb a nákupní profil kontaktu.

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

## Načtení nastavení e-commerce — GET /commerce/settings

> Načtěte měnu workspace, okna pro přiřazení tržeb a dobu, po které se košík stane opuštěným. Alfaverze: otevřená jen týmu Emailitu.

# Načtení nastavení e-commerce

Načte nastavení E-commerce ve workspace. Workspace, který ho nikdy nezměnil, dostane výchozí hodnoty. 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 /commerce/settings`

## Objekt nastavení

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

- `currency` (string): Třípísmenný kód ISO 4217, který se použije u objednávek a košíků, jež žádnou měnu neuvádějí. Výchozí hodnota je `USD`.

- `attribution_click_days` (integer): Nová objednávka se připíše e-mailu z kampaně nebo automatizace, na který kupující naposledy klikl během tohoto počtu dní před objednávkou. Výchozí hodnota je `5`.

- `attribution_open_days` (integer): Bez prokliku se objednávka připíše e-mailu, který kupující naposledy otevřel během tohoto počtu dní. Při `0` se připisují jen prokliky. Výchozí hodnota je `1`.

- `cart_abandon_minutes` (integer): Košík kontaktu s položkami, který se tolik minut neaktualizuje, se stane opuštěným a vyvolá `cart.abandoned`. Výchozí hodnota je `60`.

**Požadavek** `GET /commerce/settings`

**cURL**

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

**200**

```json
{
  "object": "commerce_settings",
  "currency": "USD",
  "attribution_click_days": 5,
  "attribution_open_days": 1,
  "cart_abandon_minutes": 60
}
```

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

## Úprava nastavení e-commerce — POST /commerce/settings

> Změňte měnu workspace, okna pro přiřazení tržeb nebo dobu, po které se košík stane opuštěným. Alfaverze: otevřená jen týmu Emailitu.

# Úprava nastavení e-commerce

Změní nastavení E-commerce ve workspace. Změní se jen pole, která pošlete. Přiřazení tržeb se nastavuje při prvním uložení objednávky, takže nová okna platí pro objednávky uložené potom. 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).

`POST /commerce/settings`

## Tělo požadavku

- `currency` (string): Třípísmenný kód ISO 4217, například `EUR`. Použije se u objednávek a košíků, které žádnou měnu neuvádějí.

- `attribution_click_days` (integer): Okno pro proklik ve dnech, od 1 do 30.

- `attribution_open_days` (integer): Okno pro otevření ve dnech, od 0 do 30. Při `0` se připisují jen prokliky.

- `cart_abandon_minutes` (integer): Počet minut bez aktualizace, po kterém se košík kontaktu stane opuštěným, od 15 do 10 080 (7 dní).

## Odpověď

`200 OK` se všemi [nastaveními](/cs/docs/api-reference/commerce/get-settings/). Pokud je některá hodnota mimo povolený rozsah, vrací `422`.
**Požadavek** `POST /commerce/settings`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/commerce/settings \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "currency": "EUR", "attribution_open_days": 0, "cart_abandon_minutes": 120 }'
```

**200**

```json
{
  "object": "commerce_settings",
  "currency": "EUR",
  "attribution_click_days": 5,
  "attribution_open_days": 0,
  "cart_abandon_minutes": 120
}
```

**422**

```json
{
  "message": "Validation failed. cart_abandon_minutes: Must be a whole number from 15 to 10080.",
  "errors": {
    "cart_abandon_minutes": [
      "Must be a whole number from 15 to 10080."
    ]
  }
}
```

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

## Načtení přehledu e-commerce — GET /commerce/overview

> Tržby, tržby z e-mailů, zákazníci, košíky, denní řada, nejlepší produkty a nejlepší kampaně za zvolené období. Alfaverze: otevřená jen týmu Emailitu.

# Načtení přehledu e-commerce

Načte čísla, která zobrazuje **Email Marketing → Commerce**, za zvolené období. 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).

Tržby jsou celková částka objednávky minus vrácené peníze a zrušené objednávky se nepočítají. Částky se seskupují podle měny a nikdy se nepřevádějí, takže většina polí jsou seznamy s jednou položkou pro každou měnu.

`GET /commerce/overview`

## Parametry dotazu

- `from` (string): Začátek období, datum, nebo datum a čas ve formátu ISO 8601. Výchozí hodnota je 30 dní před `to`.

- `to` (string): Konec období, který do něj nepatří. Výchozí hodnota je aktuální čas. Období může být dlouhé nejvýše 366 dní.

## Odpověď

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

- `from, to` (string): Použité období ve formátu ISO 8601 v UTC.

- `totals` (object[]): Všechny objednávky zadané v daném období, pro každou měnu zvlášť, seřazené od nejvyšších tržeb: `currency`, `orders`, `revenue`, `buyers` a `average_order_value`.

- `attributed` (object[]): Objednávky připsané e-mailu, podle `channel` (`campaigns`, nebo `automations`) a `currency`, s `orders`, `revenue` a `buyers`.

- `customers` (object): - `new`: kontakty, jejichž první objednávka spadá do daného období. - `returning`: kontakty, jejichž první objednávka byla před `from` a které od `from` objednaly znovu.

- `carts` (object): Košíky naposledy upravené v daném období: `active`, `abandoned` a `recovered` (převedené na objednávku poté, co byly opuštěné). `abandoned_by_currency` uvádí počet opuštěných košíků `carts` a jejich celkovou hodnotu `value` pro každou měnu `currency`, seřazené od nejvyšší hodnoty, a `abandoned_value` a `abandoned_currency` opakují první z nich.

- `series` (object[]): Jedna položka pro každý den a měnu, ve kterých byly objednávky: `date` (`YYYY-MM-DD`), `currency`, `orders`, `revenue` a `attributed_revenue`.

- `top_products` (object[]): Až 10 produktů podle tržeb z položek: `product_id` (ID produktu ve vašem obchodě), `title`, `image_url`, `currency`, `quantity` a `revenue`.

- `top_campaigns` (object[]): Až 5 kampaní podle připsaných tržeb: `campaign_id`, `name`, `currency`, `orders` a `revenue`.

Pokud `from` nebo `to` není platné datum, `from` není před `to` nebo je období delší než 366 dní, vrací `422`.
**Požadavek** `GET /commerce/overview`

**cURL**

```bash
curl "https://api.emailit.com/v2/commerce/overview?from=2026-09-10&to=2026-10-10" \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "object": "commerce_overview",
  "from": "2026-09-10T00:00:00.000Z",
  "to": "2026-10-10T00:00:00.000Z",
  "totals": [
    {
      "currency": "USD",
      "orders": 1284,
      "revenue": 108422.6,
      "buyers": 1007,
      "average_order_value": 84.44
    }
  ],
  "attributed": [
    {
      "channel": "campaigns",
      "currency": "USD",
      "orders": 312,
      "revenue": 27140.3,
      "buyers": 288
    },
    {
      "channel": "automations",
      "currency": "USD",
      "orders": 158,
      "revenue": 13981.2,
      "buyers": 149
    }
  ],
  "customers": {
    "new": 604,
    "returning": 403
  },
  "carts": {
    "active": 37,
    "abandoned": 412,
    "recovered": 66,
    "abandoned_value": 35210.8,
    "abandoned_currency": "USD",
    "abandoned_by_currency": [
      { "currency": "USD", "carts": 412, "value": 35210.8 }
    ]
  },
  "series": [
    {
      "date": "2026-10-08",
      "currency": "USD",
      "orders": 51,
      "revenue": 4318.4,
      "attributed_revenue": 1702.9
    },
    {
      "date": "2026-10-09",
      "currency": "USD",
      "orders": 44,
      "revenue": 3720.15,
      "attributed_revenue": 1188.6
    }
  ],
  "top_products": [
    {
      "product_id": "8123456789",
      "title": "Trail running shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg",
      "currency": "USD",
      "quantity": 214,
      "revenue": 18190
    }
  ],
  "top_campaigns": [
    {
      "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
      "name": "October newsletter",
      "currency": "USD",
      "orders": 214,
      "revenue": 18364.3
    }
  ]
}
```

**422**

```json
{
  "message": "Validation failed. from: Use an ISO from/to range of at most 366 days.",
  "errors": {
    "from": [
      "Use an ISO from/to range of at most 366 days."
    ]
  }
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/commerce/overview/

## Načtení nákupního profilu kontaktu — GET /contacts/{id}/commerce

> Načtěte nákupní metriky kontaktu, riziko odchodu, nedávné objednávky, otevřený košík a nedávno zobrazené produkty. Alfaverze: otevřená jen týmu Emailitu.

# Načtení nákupního profilu kontaktu

Načte, co kontakt koupil a prohlížel: nákupní metriky, 10 nejnovějších objednávek, otevřený košík a nedávno zobrazené produkty. Webové rozhraní zobrazuje stejná data v panelu **Purchases** na stránce kontaktu. 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 /contacts/{id}/commerce`

## Parametry v cestě

- `id` (string, povinné): ID kontaktu (`con_...`), nebo e-mailová adresa kontaktu. E-mailové adresy zakódujte pro URL.

## Odpověď

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

- `contact_id` (string): ID kontaktu (`con_...`).

- `metrics` (object): Nákupní metriky, přepočítané při každém zápisu objednávky. Počítají všechny objednávky kromě zrušených a odečítají vrácené peníze. Když kontakt objednával ve více měnách, počítají se jen objednávky v měně jeho poslední objednávky. - `orders_count` (integer), `total_spent` (number), `average_order_value` (number), `currency` (string nebo null). - `first_order_at`, `last_order_at` (string nebo null). - `expected_next_order_at` (string nebo null): poslední objednávka plus průměrná doba mezi objednávkami kontaktu. Nastavuje se od druhé objednávky. - `churn_risk` (string nebo null): `low`, `medium` nebo `high`. Porovnává dobu od poslední objednávky s průměrným odstupem mezi objednávkami kontaktu (nejméně 14 dní), nebo po jediné objednávce s 90 dny. V rámci odstupu je `low`, až do dvojnásobku odstupu `medium`, potom `high`. Bez objednávek `null`. - `last_active_at` (string nebo null): poslední aktivita na vašem webu, kterou nahlásil měřicí skript. - `timezone` (string nebo null): časové pásmo IANA, které nahlásil prohlížeč kontaktu. Používá se při [odeslání v místním čase](/cs/docs/api-reference/campaigns/send/).

- `orders` (object[]): 10 naposledy zadaných [objednávek](/cs/docs/api-reference/orders/get/) kontaktu.

- `orders_total` (integer): Počet objednávek kontaktu, včetně zrušených. Pokud je chcete procházet po stránkách, použijte [Výpis objednávek](/cs/docs/api-reference/orders/list/) s `contact_id`.

- `open_cart` (object | null): Naposledy upravený [košík](/cs/docs/api-reference/carts/get/) kontaktu, který je ve stavu `active` nebo `abandoned` a obsahuje položky, nebo `null`.

- `recently_viewed` (object[]): Až 12 produktů, které si kontakt zobrazil za posledních 90 dní, nejnovější jako první, podle hlášení měřicího skriptu. Archivované produkty a produkty, které nejsou skladem, se vynechají. Každý má `id` (ID produktu ve vašem obchodě), `title`, `url`, `image_url`, `price`, `price_formatted`, `currency` a `on_sale`.

Pokud parametru `id` neodpovídá žádný kontakt, vrací `404`.
**Požadavek** `GET /contacts/{id}/commerce`

**cURL**

```bash
curl https://api.emailit.com/v2/contacts/con_3EwrXnu9OaQWlfI1AyPUUEoYjQs/commerce \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "object": "contact_commerce",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "metrics": {
    "orders_count": 3,
    "total_spent": 276.3,
    "average_order_value": 92.1,
    "currency": "USD",
    "first_order_at": "2026-03-14T10:12:00.000Z",
    "last_order_at": "2026-10-08T14:32:10.000Z",
    "expected_next_order_at": "2027-01-20T16:42:15.000Z",
    "churn_risk": "low",
    "last_active_at": "2026-10-09T18:03:27.000Z",
    "timezone": "Europe/London"
  },
  "orders": [
    {
      "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": null,
      "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"
    }
  ],
  "orders_total": 3,
  "open_cart": null,
  "recently_viewed": [
    {
      "id": "8123456790",
      "title": "Merino running socks",
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg",
      "price": 9,
      "price_formatted": "$9.00",
      "currency": "USD",
      "on_sale": false
    }
  ]
}
```

**404**

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

---
Zdroj: https://emailit.com/cs/docs/api-reference/commerce/contact-commerce/