# Košíky API

> Posílejte košíky kupujících, aby Emailit poznal opuštěné košíky.

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

## Vytvoření nebo úprava košíku — POST /carts

> Pošlete aktuální košík kupujícího ze svého obchodu. Nečinné košíky známých kontaktů se stanou opuštěnými a vyvolají cart.abandoned. Alfaverze: otevřená jen týmu Emailitu.

# Vytvoření nebo úprava košíku

Pošlete aktuální košík kupujícího pokaždé, když se změní. Klíčem košíku je jeho `id` ve vašem obchodě: když stejné `id` pošlete znovu, uložený košík se upraví. Každé volání nahradí `items` a `total` košíku. E-mail, kontakt, měna a URL pokladny se zachovají, když je vynecháte. 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).

Košíky může místo toho posílat z prohlížeče [měřicí skript](/cs/docs/commerce/connect-your-shop/#the-tracking-script).

Nový košík nebo změna položek, celkové částky, stavu nebo kontaktu košíku vyvolá událost [`cart.updated`](/cs/docs/webhooks/events/cart/updated/). Opakované odeslání stejného košíku nevyvolá nic.

Jak košík přechází mezi stavy:

- **Opuštěný.** Košík, který patří kontaktu, obsahuje aspoň jednu položku a neaktualizuje se po dobu `cart_abandon_minutes` z [nastavení E-commerce](/cs/docs/api-reference/commerce/get-settings/) (ve výchozím stavu 60), přejde do stavu `abandoned` a Emailit vyvolá [`cart.abandoned`](/cs/docs/webhooks/events/cart/abandoned/). Košíky bez kontaktu zůstávají ve stavu `active`.
- **Znovu aktivní.** Úprava opuštěného košíku ho vrátí do stavu `active` a vymaže `abandoned_at`.
- **Převedený.** [Objednávka](/cs/docs/api-reference/orders/create/) se stejným `cart_id` košík převede. Nová objednávka od stejného kontaktu převede také košíky tohoto kontaktu, které se naposledy změnily před objednávkou. Převedený košík zůstane převedený, i když ho upravíte.

`POST /carts`

## Tělo požadavku

- `id` (string | number, povinné): ID košíku nebo pokladny ve vašem obchodě, nejvýše 255 znaků. Ukládá se jako `external_id`. Stejnou hodnotu pošlete v objednávce jako `cart_id`. Můžete ho poslat také jako `external_id` nebo `cart_id`.

- `email` (string): Kontaktní e-mail kupujícího. Propojí košík s kontaktem s touto adresou. Košíky nikdy nevytvářejí kontakty: košík bez odpovídajícího kontaktu se nemůže stát opuštěným. 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`.

- `anonymous_id` (string): ID návštěvníka z měřicího skriptu, nejvýše 255 znaků. Když se tento návštěvník později identifikuje, košíky s tímto ID a bez kontaktu se s kontaktem propojí.

- `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/).

- `items` (object[]): Až 250 položek ve stejném formátu jako `items` endpointu [Vytvoření nebo úprava objednávky](/cs/docs/api-reference/orders/create/). Položky bez `title`, `url` nebo `image_url` je převezmou z [katalogu](/cs/docs/api-reference/products/create/). Přijímá se také `line_items`.

- `total` (number | string): Hodnota košíku. Výchozí hodnota je součet částek položek.

- `checkout_url` (string): Odkaz `http` nebo `https`, který kupujícího vrátí k tomuto košíku, nejvýše 2 048 znaků. E-maily na něj mohou odkazovat pomocí [bloku košíku](/cs/docs/campaigns/products-and-coupons/#the-cart).

- `status` (string): `active` (výchozí hodnota), nebo `converted`. Pokud chcete košík uzavřít sami, pošlete `converted`.

## Odpověď

`201 Created` s [objektem košíku](/cs/docs/api-reference/carts/get/), když je košík nový, nebo `200 OK`, když se upravil existující košík. Pokud je některé pole neplatné, vrací `422`.
**Požadavek** `POST /carts`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/carts \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "c-58f1a2",
    "email": "ada@example.com",
    "currency": "USD",
    "checkout_url": "https://shop.example.com/cart/recover/c-58f1a2",
    "items": [
      { "product_id": "8123456789", "variant_id": "42-blue", "sku": "TRS-BLU-42", "quantity": 1, "price": 89 }
    ]
  }'
```

**201**

```json
{
  "object": "cart",
  "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
  "external_id": "c-58f1a2",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "active",
  "currency": "USD",
  "total": 89,
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "url": "https://shop.example.com/products/trail-running-shoe",
      "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
    }
  ],
  "checkout_url": "https://shop.example.com/cart/recover/c-58f1a2",
  "source": "api",
  "abandoned_at": null,
  "converted_at": null,
  "converted_order_id": null,
  "created_at": "2026-10-08T12:12:47.630Z",
  "updated_at": "2026-10-08T12:12:47.630Z"
}
```

**422**

```json
{
  "message": "Validation failed. checkout_url: must be an http(s) URL",
  "errors": {
    "checkout_url": [
      "must be an http(s) URL"
    ]
  }
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/carts/upsert/

## Načtení košíku — GET /carts/{id}

> Načtěte košík podle jeho ID v Emailitu nebo podle ID košíku či pokladny ve vašem obchodě. Alfaverze: otevřená jen týmu Emailitu.

# Načtení košíku

Načte košík podle jeho ID v Emailitu nebo podle ID košíku či pokladny ve vašem obchodě. 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 /carts/{id}`

## Parametry v cestě

- `id` (string, povinné): ID košíku (`crt_...`), nebo ID košíku či pokladny ve vašem obchodě (`external_id`). ID z obchodu, která obsahují speciální znaky, zakódujte pro URL.

## Objekt košíku

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

- `id` (string): ID košíku v Emailitu (`crt_...`).

- `external_id` (string): ID košíku nebo pokladny ve vašem obchodě: `id`, které jste poslali. Košíky z měřicího skriptu bez vlastního ID používají `web:` a za ním anonymní ID návštěvníka.

- `contact_id` (string | null): Kontakt, kterému košík patří (`con_...`), nebo `null`, dokud kupující není známý.

- `email` (string | null): Kontaktní e-mail kupujícího.

- `status` (string): - `active`: kupující ještě nakupuje. - `abandoned`: košík patří kontaktu, obsahuje položky a nezměnil se po dobu `cart_abandon_minutes` z [nastavení E-commerce](/cs/docs/api-reference/commerce/get-settings/). - `converted`: z košíku vznikla objednávka, nebo jste ho poslali se `status` nastaveným na `converted`.

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

- `total` (number): Hodnota košíku.

- `items` (object[]): Položky košíku. Každá má `product_id` (ID produktu ve vašem obchodě), `variant_id`, `sku`, `title`, `quantity`, `unit_price`, `total`, `url` a `image_url`.

- `checkout_url` (string | null): Odkaz, který kupujícího vrátí k tomuto košíku.

- `source` (string): `api`, nebo `js` u košíků z měřicího skriptu.

- `abandoned_at` (string | null): Kdy byl košík označen jako opuštěný. Vymaže se, když se košík znovu upraví.

- `converted_at` (string | null): Kdy byl košík převeden na objednávku.

- `converted_order_id` (string | null): Objednávka (`ord_...`), která košík převedla.

- `created_at, updated_at` (string): Kdy byl košík poprvé uložen a kdy se naposledy změnil, ve formátu ISO 8601 v UTC.

**Požadavek** `GET /carts/{id}`

**cURL**

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

**200**

```json
{
  "object": "cart",
  "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
  "external_id": "c-58f1a2",
  "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
  "email": "ada@example.com",
  "status": "abandoned",
  "currency": "USD",
  "total": 107,
  "items": [
    {
      "product_id": "8123456789",
      "variant_id": "42-blue",
      "sku": "TRS-BLU-42",
      "title": "Trail running shoe",
      "quantity": 1,
      "unit_price": 89,
      "total": 89,
      "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,
      "url": "https://shop.example.com/products/merino-running-socks",
      "image_url": "https://shop.example.com/images/merino-running-socks.jpg"
    }
  ],
  "checkout_url": "https://shop.example.com/cart/recover/c-58f1a2",
  "source": "api",
  "abandoned_at": "2026-10-08T13:31:04.118Z",
  "converted_at": null,
  "converted_order_id": null,
  "created_at": "2026-10-08T12:12:47.630Z",
  "updated_at": "2026-10-08T12:28:51.902Z"
}
```

**404**

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

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

## Výpis košíků — GET /carts

> Vypište košíky od naposledy upravených, filtrované podle stavu nebo kontaktu. Alfaverze: otevřená jen týmu Emailitu.

# Výpis košíků

Vypíše košíky, naposledy upravené 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 /carts`

## Parametry dotazu

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

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

- `status` (string): Jen košíky v tomto stavu: `active`, `abandoned` nebo `converted`.

- `contact_id` (string): Jen košíky tohoto kontaktu (`con_...`).

- `match`, `order`, `direction`: viz [Filtrování](https://emailit.com/cs/docs/api-reference/filtering/).

## Filtry a řazení

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

## Odpověď

Stránka [objektů košíků](/cs/docs/api-reference/carts/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é filtry.
**Požadavek** `GET /carts`

**cURL**

```bash
curl "https://api.emailit.com/v2/carts?status=abandoned&order=abandoned_at&direction=desc" \
  -H "Authorization: Bearer your_api_key"
```

**200**

```json
{
  "data": [
    {
      "object": "cart",
      "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
      "external_id": "c-58f1a2",
      "contact_id": "con_3EwrXnu9OaQWlfI1AyPUUEoYjQs",
      "email": "ada@example.com",
      "status": "abandoned",
      "currency": "USD",
      "total": 89,
      "items": [
        {
          "product_id": "8123456789",
          "variant_id": "42-blue",
          "sku": "TRS-BLU-42",
          "title": "Trail running shoe",
          "quantity": 1,
          "unit_price": 89,
          "total": 89,
          "url": "https://shop.example.com/products/trail-running-shoe",
          "image_url": "https://shop.example.com/images/trail-running-shoe.jpg"
        }
      ],
      "checkout_url": "https://shop.example.com/cart/recover/c-58f1a2",
      "source": "api",
      "abandoned_at": "2026-10-08T13:31:04.118Z",
      "converted_at": null,
      "converted_order_id": null,
      "created_at": "2026-10-08T12:12:47.630Z",
      "updated_at": "2026-10-08T12:28:51.902Z"
    }
  ],
  "total_records": 1,
  "next_page_url": null,
  "previous_page_url": null
}
```

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

## Smazání košíku — DELETE /carts/{id}

> Smažte košík. Alfaverze: otevřená jen týmu Emailitu.

# Smazání košíku

Smaže košík. Objednávek, které ho převedly, se to nedotkne. Pokud košík se stejným `id` pošlete znovu, uloží se jako nový košík. 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 /carts/{id}`

## Parametry v cestě

- `id` (string, povinné): ID košíku (`crt_...`), nebo ID košíku či pokladny ve vašem obchodě.

**Požadavek** `DELETE /carts/{id}`

**cURL**

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

**200**

```json
{
  "object": "cart",
  "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
  "deleted": true
}
```

**404**

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

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