Přejít na obsah
Dokumentace

Košíky

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

Základní URLhttps://api.emailit.com/v2AutentizaceChybyLimity rychlosti

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.

Košíky může místo toho posílat z prohlížeče měřicí skript.

Nový košík nebo změna položek, celkové částky, stavu nebo kontaktu košíku vyvolá událost 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 (ve výchozím stavu 60), přejde do stavu abandoned a Emailit vyvolá 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 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

idstring | numberPovinné

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.

emailstring

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_idstring

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

anonymous_idstring

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

currencystring

Třípísmenný kód ISO 4217. Výchozí hodnota je měna workspace v nastavení E-commerce.

itemsobject[]

Až 250 položek ve stejném formátu jako items endpointu Vytvoření nebo úprava objednávky. Položky bez title, url nebo image_url je převezmou z katalogu. Přijímá se také line_items.

totalnumber | string

Hodnota košíku. Výchozí hodnota je součet částek položek.

checkout_urlstring

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.

statusstring

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

Odpověď

201 Created s objektem košíku, když je košík nový, nebo 200 OK, když se upravil existující košík. Pokud je některé pole neplatné, vrací 422.

POST/carts
Terminal
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 }
    ]
  }'
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"
}

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.

GET/carts/{id}

Parametry v cestě

idstringPovinné

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

objectstring

Vždy cart.

idstring

ID košíku v Emailitu (crt_...).

external_idstring

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_idstring | null

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

emailstring | null

Kontaktní e-mail kupujícího.

statusstring

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

  • converted: z košíku vznikla objednávka, nebo jste ho poslali se status nastaveným na converted.

currencystring | null

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

totalnumber

Hodnota košíku.

itemsobject[]

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_urlstring | null

Odkaz, který kupujícího vrátí k tomuto košíku.

sourcestring

api, nebo js u košíků z měřicího skriptu.

abandoned_atstring | null

Kdy byl košík označen jako opuštěný. Vymaže se, když se košík znovu upraví.

converted_atstring | null

Kdy byl košík převeden na objednávku.

converted_order_idstring | null

Objednávka (ord_...), která košík převedla.

created_at, updated_atstring

Kdy byl košík poprvé uložen a kdy se naposledy změnil, ve formátu ISO 8601 v UTC.

GET/carts/{id}
Terminal
curl https://api.emailit.com/v2/carts/crt_3Rx784H7VYWRTViadjbp5oKHRud \
  -H "Authorization: Bearer your_api_key"
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"
}

Výpis košíků

Vypíše košíky, naposledy upravené jako první. Vyžaduje API klíč s oprávněním full.

GET/carts

Parametry dotazu

pageinteger

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

limitinteger

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

statusstring

Jen košíky v tomto stavu: active, abandoned nebo converted.

contact_idstring

Jen košíky tohoto kontaktu (con_...).

matchstring

Hodnota all (výchozí) vyžaduje shodu se všemi filtry. S hodnotou or stačí shoda s kterýmkoli filtrem. Viz Filtrování.

orderstring

Klíč řazení pro tento výpis. Viz klíče řazení níže.

directionstring

asc, nebo desc.

Filtry a řazení

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íčTypPodmínkyPoznámky
external_idstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
emailstringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
statusenumexact, not_exactHodnoty: active, abandoned, converted
totalnumberexact, not_exact, gt, gte, lt, lte, empty, not_empty
currencystringexact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
updated_atdateexact, before, after, empty, not_empty
abandoned_atdateexact, before, after, empty, not_empty
created_atdateexact, before, after, empty, not_empty

Klíče řazení

V parametru order předejte jeden z těchto klíčů a v parametru direction hodnotu asc, nebo desc: external_id, email, status, total, currency, updated_at, abandoned_at, created_at

Odpověď

Stránka objektů košíků 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.

GET/carts
Terminal
curl "https://api.emailit.com/v2/carts?status=abandoned&order=abandoned_at&direction=desc" \
  -H "Authorization: Bearer your_api_key"
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
}

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.

DELETE/carts/{id}

Parametry v cestě

idstringPovinné

ID košíku (crt_...), nebo ID košíku či pokladny ve vašem obchodě.

DELETE/carts/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/carts/crt_3Rx784H7VYWRTViadjbp5oKHRud \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "object": "cart",
  "id": "crt_3Rx784H7VYWRTViadjbp5oKHRud",
  "deleted": true
}

Byla tato stránka užitečná?

Děkujeme za zpětnou vazbu.

Děkujeme, čteme každou zprávu.

Esc

Oblíbené

↑↓procházet↵otevřítEsczavřít