E-commerce

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

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

GET/commerce/settings
POST/commerce/settings
GET/commerce/overview
GET/contacts/{id}/commerce

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.

GET/commerce/settings

Objekt nastavení

objectstring

Vždy commerce_settings.

currencystring

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_daysinteger

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_daysinteger

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_minutesinteger

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.

JSON

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

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

POST/commerce/settings

Tělo požadavku

currencystring

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_daysinteger

Okno pro proklik ve dnech, od 1 do 30.

attribution_open_daysinteger

Okno pro otevření ve dnech, od 0 do 30. Při 0 se připisují jen prokliky.

cart_abandon_minutesinteger

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. Pokud je některá hodnota mimo povolený rozsah, vrací 422.

POST/commerce/settings

Terminal

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 }'

JSON

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

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

Načtení přehledu e-commerce

Načte čísla, která zobrazuje Email MarketingCommerce, za zvolené období. Vyžaduje API klíč s oprávněním full.

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

fromstring

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

tostring

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ěď

objectstring

Vždy commerce_overview.

from, tostring

Použité období ve formátu ISO 8601 v UTC.

totalsobject[]

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.

attributedobject[]

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

customersobject

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.

cartsobject

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.

seriesobject[]

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_productsobject[]

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_campaignsobject[]

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.

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

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

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.

GET/contacts/{id}/commerce

Parametry v cestě

idstringPovinné

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

Odpověď

objectstring

Vždy contact_commerce.

contact_idstring

ID kontaktu (con_...).

metricsobject

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.

ordersobject[]

10 naposledy zadaných objednávek kontaktu.

orders_totalinteger

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 s contact_id.

open_cartobject | null

Naposledy upravený košík kontaktu, který je ve stavu active nebo abandoned a obsahuje položky, nebo null.

recently_viewedobject[]

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.

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

JSON

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