Use the Stats API
The /api/stats/ method family exposes the shop's statistics counters: what happens in the
shop (logons, orders, carts, subscriptions, ...), what happened with mail sendouts
(deliveries, opens, bounces, clicks) and how often tracked shop links were clicked.
It is the same data the admin area's status pages ("Status" / "Serienmails") are built on.
Access
All stats methods require an authenticated admin session (see use-api for the
session model): perform a logon with an account that has admin rights,
then call the stats methods within that session. Without admin access the methods respond with
403 and the X-oekobox-error: not_auth header (stats/eventtypes1 is the exception — it only
lists event metadata and needs no session).
Methods
| Method | Data | Response Type |
|---|---|---|
| stats/eventtypes1 | all known event codes with localized descriptions | EventType |
| stats/events1 | per-day (or per-hour) counts of one event code | EventStat |
| stats/links1 | per-day click counts for tracked shop links | LinkStat |
| stats/mailcampaigns | all mail sendouts (Serienmails) with delivery/engagement numbers | MailCampaign |
| stats/mailopens | opens over time (per hour/day) after one sendout | MailOpenStat |
| stats/campaign1 | per-week statistics of one mail campaign | CampaignStat |
| stats/mailcampaigns1 | all message series on every channel (mail, push, sms) with delivery/engagement numbers; adds channel, delivered and a channel filter |
MailCampaign v2 |
| stats/push1 | recent push notification sends, one row per delivery channel | PushSend |
| stats/pushsummary1 | per-day / per-channel push totals (sends, failed, accepted, delivered, opened) | PushDayStat |
| stats/pushdevices1 | devices registered for platform-side push, per platform and app | PushDeviceStat |
How the methods relate
The methods link into each other via shared (global) parameters — the HTML documentation
(?oo-rf=html) renders these as clickable cross references:
-
stats/eventtypes1 lists the
codevalues you can pass aseventidto stats/events1. Events cover customer activity (logons, new orders, cart changes, unsubscribes, ...), system activity and derived averages (e.g. average cart sum). -
stats/mailcampaigns is the entry point for everything mail related. Each sendout carries:
- a
serieref— pass it assidto stats/mailopens to get the opens curve of that sendout (p=hper hour for the first 72 hours,p=dper day), - a
campaignid(0 = info mail) — pass it to stats/campaign1 for the per-week campaign aggregation over all sendouts of that campaign.
- a
-
stats/links1 takes the link identifiers used by the shop navigation (
i_<itemid>,c_<groupid>,sg_<subgroupid>,r_<rubricid>,a_<assortmentid>,n_<navigationid>) and returns their daily click counts, optionally restricted withstart/endunix timestamps. -
The three
push*methods cover push notifications (see also external push provider and setup push notifications). stats/push1 lists individual sends (filter withdays,limit,channel,type,serieref), stats/pushsummary1 aggregates them per day and channel, and stats/pushdevices1 shows how many devices the platform itself can reach via FCM. Delivered/opened counts only carry information whenanalytics_capableis non-zero (the apps have to report back). Unlike the other stats methods these three also accept an API-role account, so an external push provider can read them. -
Push and SMS series (queued via send-message-series) are counted like Serienmails: stats/mailcampaigns1 shows them with
channel=push/sms,deliveredand the tap counts inuniqueopens/opens; stats/mailopens gives their taps per hour.
Notes on the data:
- Timestamps in responses are unix milliseconds (EventStat, LinkStat) or ISO datetimes (MailCampaign, MailOpenStat).
- Rates (
openrate,clickrate,bouncerate) are percentages. - A sendout with
duration = 0is still running; its counters are not final yet. - Archived sendouts are excluded from stats/mailcampaigns
unless
archived=trueis passed.
Ideas — what to build with this data
- A mailing performance dashboard. Pull stats/mailcampaigns and chart open/click/bounce rates over time. Compare subject lines: which wording gets opened, which gets clicked? The per-week view of stats/campaign1 shows whether a recurring campaign wears out its audience.
- Find the best sendout time. The opens curve from stats/mailopens shows how quickly readers react after a sendout. Comparing curves of sendouts started at different weekdays/hours tells you when your audience actually reads mail.
- Bounce and unsubscribe monitoring. Poll stats/mailcampaigns
after each sendout and alert when
bouncerateorunsubscribesjump above your baseline — an early warning for list-quality or content problems. - Correlate mailings with shop activity. Combine a sendout's date with
stats/events1 (e.g. new orders, logons, cart events, hourly
resolution via
hourly=true): did the newsletter actually move orders, and with what delay? - Measure what the mail advertised. If a sendout promotes specific items or categories, fetch their click counts from stats/links1 for the days after the sendout and compare against the week before.
- A weekly shop report. A scheduled job can collect the key event series (orders, new customers, unsubscribes, average cart sum) from stats/events1 plus the latest sendouts and render a compact report mail or chat message for the shop owner.
- Push funnel. stats/pushsummary1 gives sends → accepted →
delivered → opened per day; compare channels, or check that an external push provider keeps
its
failedcount at zero after a switch-over. - Sortiment/navigation heatmaps. stats/links1 over all categories highlights which parts of the assortment get attention — and which are never clicked at all.
Getting started
# logon (admin account)
GET <base>/api/logon4?cid=<email>&pass=<password>
# list the sendouts
GET <base>/api/stats/mailcampaigns?oo-rf=json
# opens curve of one sendout
GET <base>/api/stats/mailopens?sid=<serieref>&p=h&oo-rf=json
# per-week campaign details
GET <base>/api/stats/campaign1?campaignid=<id>&oo-rf=json
Use ?oo-rf=html on any method to explore its parameters, error codes and response schema
interactively.