Commerce

Commerce settings, the revenue overview and a contact’s purchase profile.

Base URLhttps://api.emailit.com/v2Authentication Errors Rate limits

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

Retrieve commerce settings

Retrieve the commerce settings of the workspace. A workspace that never changed them gets the defaults. Requires an API key with the full scope.

GET/commerce/settings

The settings object

objectstring

Always commerce_settings.

currencystring

Three-letter ISO 4217 code used for orders and carts that don’t name a currency. Default USD.

attribution_click_daysinteger

A new order is credited to the campaign or automation email the buyer last clicked within this many days before the order. Default 5.

attribution_open_daysinteger

Without a click, the order is credited to the email the buyer last opened within this many days. 0 credits clicks only. Default 1.

cart_abandon_minutesinteger

A contact’s cart with items that isn’t updated for this many minutes becomes abandoned and emits cart.abandoned. Default 60.

JSON

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

Update commerce settings

Change the commerce settings of the workspace. Only the fields you send change. Attribution is set when an order is first stored, so new windows apply to orders stored afterwards. Requires an API key with the full scope.

POST/commerce/settings

Request Body

currencystring

Three-letter ISO 4217 code, such as EUR. Used for orders and carts that don’t name a currency.

attribution_click_daysinteger

Click window in days, from 1 to 30.

attribution_open_daysinteger

Open window in days, from 0 to 30. 0 credits clicks only.

cart_abandon_minutesinteger

Minutes without an update before a contact’s cart becomes abandoned, from 15 to 10,080 (7 days).

Returns

200 OK with all the settings. Returns 422 when a value is out of range.

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

Retrieve the commerce overview

Retrieve the numbers behind Email MarketingCommerce for a date range. Requires an API key with the full scope.

Revenue is the order total minus refunds, and canceled orders don’t count. Amounts are grouped by currency and never converted, so most fields are lists with one entry per currency.

GET/commerce/overview

Query Parameters

fromstring

Start of the range, an ISO 8601 date or date-time. Defaults to 30 days before to.

tostring

End of the range, not included. Defaults to now. The range can be up to 366 days long.

Returns

objectstring

Always commerce_overview.

from, tostring

The range used, in ISO 8601 UTC.

totalsobject[]

All orders placed in the range, per currency, highest revenue first: currency, orders, revenue, buyers and average_order_value.

attributedobject[]

Orders credited to an email, per channel (campaigns or automations) and currency, with orders, revenue and buyers.

customersobject

new: contacts whose first order is in the range.
returning: contacts whose first order was before from and who ordered again since from.

cartsobject

Carts last updated in the range: active, abandoned and recovered (converted after being abandoned). abandoned_by_currency lists the abandoned carts’ carts count and total value per currency, highest value first, and abandoned_value and abandoned_currency repeat the first one.

seriesobject[]

One entry per day and currency with orders: date (YYYY-MM-DD), currency, orders, revenue and attributed_revenue.

top_productsobject[]

Up to 10 products by item revenue: product_id (the product ID in your shop), title, image_url, currency, quantity and revenue.

top_campaignsobject[]

Up to 5 campaigns by credited revenue: campaign_id, name, currency, orders and revenue.

Returns 422 if from or to isn’t a valid date, from isn’t before to, or the range is longer than 366 days.

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

Retrieve a contact’s purchase profile

Retrieve what a contact bought and browsed: the purchase metrics, the 10 most recent orders, the open cart and recently viewed products. The dashboard shows the same data in the Purchases card of the contact’s page. Requires an API key with the full scope.

GET/contacts/{id}/commerce

Path Parameters

idstringRequired

The contact ID (con_...) or the contact’s email address. URL-encode email addresses.

Returns

objectstring

Always contact_commerce.

contact_idstring

The contact ID (con_...).

metricsobject

Purchase metrics, recalculated on every order write. They count every order except canceled ones and subtract refunds. When the contact ordered in several currencies, only the orders in the currency of their latest order count.

orders_count (integer), total_spent (number), average_order_value (number), currency (string or null).
first_order_at, last_order_at (string or null).
expected_next_order_at (string or null): the last order plus the contact’s average time between orders. Set from the second order on.
churn_risk (string or null): low, medium or high. Compares the time since the last order with the contact’s average gap between orders (at least 14 days), or with 90 days after a single order. Within the gap it’s low, up to twice the gap medium, after that high. null without orders.
last_active_at (string or null): the last activity the tracking script reported on your site.
timezone (string or null): the IANA time zone reported by the contact’s browser. Used by local time sends.

ordersobject[]

The 10 most recently placed orders of the contact.

orders_totalinteger

Number of orders of the contact, including canceled ones. Use List orders with contact_id to page through them.

open_cartobject | null

The contact’s most recently updated cart that is active or abandoned and has items, or null.

recently_viewedobject[]

Up to 12 products the contact viewed in the last 90 days, most recent first, as reported by the tracking script. Archived and out-of-stock products are left out. Each has id (the product ID in your shop), title, url, image_url, price, price_formatted, currency and on_sale.

Returns 404 if no contact matches id.

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