--- title: "Dashboard headline metrics" method: POST path: "/metrics/summary" tags: ["Metrics"] --- # Dashboard headline metrics `POST /metrics/summary` Pre-computed headline scalar metrics for a date range, matching the Reacher dashboard's top-level KPIs exactly. Use this for summary cards and headline numbers. Includes derived metrics like active_creators (distinct count, not daily sum), gmv_per_video, and gmv_per_sample, plus sc_affiliate_live_gmv (creator LIVE GMV as Seller Center reports it — order-date attributed, so it does not match live_gmv). Also includes Seller Center whole-shop cards: orders, units_sold, aov, ctr, conversion_rate (all-channel; aov/ctr/conversion_rate are ratios computed over the full window). Defaults to the last 30 days if no dates are specified. Dates default to the newest day with settled data for the shop (typically yesterday; up to 2 days back while a day finalizes). ## Request body - MetricsSummaryRequest — POST /metrics/summary request body. - `start_date` string, date, nullable - `end_date` string, date, nullable ## Response `200` Successful Response - MetricsSummaryResponse — Pre-computed headline scalars matching dashboard KPIs. All metrics use the analytics registry (same queries as the dashboard). A null value means the metric errored — check _errors for details. - `gmv` number, nullable — **Affiliate-attributed** GMV for the period — Reacher's view of creator-driven sales. This is NOT the shop's full GMV. For the headline number that matches the customer's TikTok Seller Center dashboard (which includes ads / Smart+ and organic), use ``total_gmv`` or the dedicated ``POST /shop-gmv/*`` endpoints. - `total_gmv` number, nullable — **Full shop** GMV for the period — includes ads / Smart+ and organic revenue, not just affiliate-attributed sales. Sourced from the TikTok Seller Center scrape. Coverage is rolling out per-shop; shops not yet covered return ``0``. For per-day breakdown by channel (video / live / product_card) and explicit per-shop currency handling, use ``POST /shop-gmv/*`` instead. - `live_gmv` number, nullable — **Creator LIVE-attributed** GMV for the period — the value shops see on TikTok's Affiliate Center → LIVE streams (/insights/transaction-analysis). Sourced from ``customers.live_sessions`` (affiliate_gmv), a DIFFERENT source than ``gmv`` (all affiliate revenue) and ``total_gmv`` (full shop view). Isolates the LIVE-stream slice only. Coverage is data-presence driven; shops without live-session data return ``0``. Currency is per-shop — for the currency-aware, single-shop, per-session view use the dedicated ``POST /lives/*`` endpoints. - `sc_affiliate_live_gmv` number, nullable — **Creator LIVE** GMV for the period exactly as TikTok Seller Center reports it — Analytics → By order source → Creator → Lives. Use this one to reconcile against a Seller Center export. It is NOT the same figure as ``live_gmv``, which comes from Affiliate Center and attributes revenue on transaction date rather than order date; the two will not match. Sourced from the same Seller Center daily rollup as ``total_gmv``, so the same caveats apply: coverage is rolling out per-shop and uncovered shops return ``0``, and currency is per-shop (multi-shop requests sum across currencies). For the per-day channel breakdown use ``POST /shop-gmv/*``. - `active_creators` number, nullable — Distinct creators with activity in the period (not summed daily counts) - `video_views` number, nullable — Total video views in the period - `videos_posted` number, nullable — New videos posted in the period - `samples_approved` number, nullable — Samples approved in the period - `gmv_per_video` number, nullable — Avg GMV per video posted in the period. Matches dashboard 'GMV per Video' - `gmv_per_sample` number, nullable — Avg GMV per sample. Matches dashboard 'GMV per Sample' - `sample_requests` number, nullable — Total sample requests in the period - `gmv_driving_videos` number, nullable — Videos that generated sales in the period - `new_creators_posting` number, nullable — First-time creators who posted in the period - `open_collabs` number, nullable — Open collaboration affiliates added - `accepted_tc_count` number, nullable — Accepted target collaborations - `creators_reached` number, nullable — Creators reached via outreach - `creators_messaged` number, nullable — Creators messaged - `tc_invites_sent` number, nullable — Target collaboration invites sent - `emails_sent` number, nullable — Emails sent - `dm_responses` number, nullable — Sum of daily unique DM responses (not deduplicated across the period) - `reply_rate` number, nullable — DM reply rate: (dm_responses / dm_messages_sent) * 100 - `orders` number, nullable — Whole-shop orders for the period across all sales channels, from TikTok Seller Center. Shops not yet on the Seller Center daily sync return ``0``. - `units_sold` number, nullable — Whole-shop units sold for the period across all sales channels, from TikTok Seller Center. ``0`` for shops not yet covered. - `aov` number, nullable — Average order value for the period (total GMV / total orders over the date range, not an average of daily AOV). ``0`` when the shop has no orders or is not yet covered. - `ctr` number, nullable — Click-through rate as a percent for the period (total clicks / total impressions over the date range). ``0`` when uncovered or no impressions. - `conversion_rate` number, nullable — Conversion rate as a percent for the period (total orders / total clicks over the date range). ``0`` when uncovered or no clicks. - `errors` string[], nullable — Metric keys that failed (null values in response) - `start_date` string, required - `end_date` string, required - `currency` string, required - `shops_queried` string[], nullable — Shop names included when querying multiple shops (x-shop-id: all or comma-separated). ## Other responses - `422` — Validation Error --- [API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) · [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/reacherapp/reacher-data-api/revisions/5eefff009b5b/schema)