---
title: "Client-report snapshot: every report field, or why it is missing"
method: POST
path: "/shop-report/snapshot"
tags: ["Shop Report"]
---

# Client-report snapshot: every report field, or why it is missing

`POST /shop-report/snapshot`

## Request

- Base URL: `https://api.reacherapp.com/public/v1`
- URL: `https://api.reacherapp.com/public/v1/shop-report/snapshot`
- Auth: API key in header `x-api-key` and API key in header `x-shop-id`

One call for a shop's client report over a window: Shop Performance Score, the six SPS health metrics, the shop's add-to-cart total, fulfillment risk (on-time dispatch, seller-fault cancellations, handling time, non-buyer-fault returns), and violations, account health and creator health. Every field has ``available``; when false, ``unavailable_reason`` and ``detail`` say why (region, not synced, no data in the window, not collected yet, or a temporary read failure) and ``drill_down_tool`` names where the detail lives. Window: a preset (default ``30d``) or start_date/end_date, max 365 days. Single-shop only.

## Request body

- ShopReportSnapshotRequest: Body for ``/shop-report/snapshot`` — a preset or explicit dates, default ``30d``.
  - `preset` string, nullable: Relative window ending at the shop's newest settled day: ``<n>d`` (1-999), ``<n>m`` (1-99) or ``all``, always capped at 365 days. Mutually exclusive with explicit dates; defaults to ``30d`` when neither is given.
  - `start_date` string, date, nullable: Inclusive window start (YYYY-MM-DD).
  - `end_date` string, date, nullable: Inclusive window end (YYYY-MM-DD).

## Response `200`

Successful Response

- ShopReportSnapshotResponse
  - `shop_id` integer, required
  - `region` string, nullable: The shop's market; null when it could not be read.
  - `start_date` string, required
  - `end_date` string, required
  - `shop_performance_score` ShopPerformanceScoreField, required
    - `available` boolean, required
    - `unavailable_reason` 'region_not_supported' | 'not_synced' | 'no_data_in_window' | 'not_collected' | 'source_unavailable', nullable: Why there is no value: ``region_not_supported`` (TikTok's official Seller Center data is US-only), ``not_synced`` (nothing stored for this shop yet), ``no_data_in_window``, ``not_collected`` (Reacher does not collect this metric yet) or ``source_unavailable`` (a temporary read failure; retry). Null when ``available`` is true.
    - `detail` string, nullable: Plain-language note to relay to the user.
    - `last_updated` string, nullable: Newest stored day behind this field (YYYY-MM-DD), when known.
    - `drill_down_tool` string, nullable: Tool that returns the detail behind this field.
    - `score` number, nullable: 0-5.
    - `tier` string, nullable
    - `as_of` string, nullable: Snapshot day of the score (YYYY-MM-DD). For a preset it can be after ``end_date``: scores are dated by TikTok's update time, so today's counts.
  - `health_metrics` HealthMetricsField, required
    - `available` boolean, required
    - `unavailable_reason` 'region_not_supported' | 'not_synced' | 'no_data_in_window' | 'not_collected' | 'source_unavailable', nullable: Why there is no value: ``region_not_supported`` (TikTok's official Seller Center data is US-only), ``not_synced`` (nothing stored for this shop yet), ``no_data_in_window``, ``not_collected`` (Reacher does not collect this metric yet) or ``source_unavailable`` (a temporary read failure; retry). Null when ``available`` is true.
    - `detail` string, nullable: Plain-language note to relay to the user.
    - `last_updated` string, nullable: Newest stored day behind this field (YYYY-MM-DD), when known.
    - `drill_down_tool` string, nullable: Tool that returns the detail behind this field.
    - `snapshot_date` string, nullable
    - `metrics` ReportHealthMetric[]
      - `metric_code` 'NRR' | 'NBFR' | 'SFCR' | 'OTDR' | 'AHT' | 'IM_DSAT', required
      - `metric_name` string, nullable
      - `status` 'EXCELLENT' | 'GOOD' | 'POOR' | 'CRITICAL' | 'NIL', required
      - `value` number, nullable
      - `value_unit` string, nullable
  - `add_to_cart` AddToCartField, required
    - `available` boolean, required
    - `unavailable_reason` 'region_not_supported' | 'not_synced' | 'no_data_in_window' | 'not_collected' | 'source_unavailable', nullable: Why there is no value: ``region_not_supported`` (TikTok's official Seller Center data is US-only), ``not_synced`` (nothing stored for this shop yet), ``no_data_in_window``, ``not_collected`` (Reacher does not collect this metric yet) or ``source_unavailable`` (a temporary read failure; retry). Null when ``available`` is true.
    - `detail` string, nullable: Plain-language note to relay to the user.
    - `last_updated` string, nullable: Newest stored day behind this field (YYYY-MM-DD), when known.
    - `drill_down_tool` string, nullable: Tool that returns the detail behind this field.
    - `total` integer, nullable: Add-to-cart count for the whole shop, summed over the window.
    - `is_complete` boolean: True only when every settled day in the window has a complete figure.
    - `days_observed` integer: Days with an add-to-cart figure.
    - `days_expected` integer: Settled days in the window, up to the newest stored day.
  - `fulfillment_risk` FulfillmentRiskField, required
    - `available` boolean, required
    - `unavailable_reason` 'region_not_supported' | 'not_synced' | 'no_data_in_window' | 'not_collected' | 'source_unavailable', nullable: Why there is no value: ``region_not_supported`` (TikTok's official Seller Center data is US-only), ``not_synced`` (nothing stored for this shop yet), ``no_data_in_window``, ``not_collected`` (Reacher does not collect this metric yet) or ``source_unavailable`` (a temporary read failure; retry). Null when ``available`` is true.
    - `detail` string, nullable: Plain-language note to relay to the user.
    - `last_updated` string, nullable: Newest stored day behind this field (YYYY-MM-DD), when known.
    - `drill_down_tool` string, nullable: Tool that returns the detail behind this field.
    - `snapshot_date` string, nullable
    - `metrics` ReportHealthMetric[]
      - `metric_code` 'NRR' | 'NBFR' | 'SFCR' | 'OTDR' | 'AHT' | 'IM_DSAT', required
      - `metric_name` string, nullable
      - `status` 'EXCELLENT' | 'GOOD' | 'POOR' | 'CRITICAL' | 'NIL', required
      - `value` number, nullable
      - `value_unit` string, nullable
    - `problem_counts` FulfillmentProblemCount[]: Per fulfillment metric, how many orders or returns TikTok counts against it over the SPS evaluation window of the newest snapshot. These are rolling-window SPS problem counts, NOT Seller Center's live order counters (ship within 24h, shipping overdue, cancellation or return requested), which stay unavailable.
      - `metric_code` 'NRR' | 'NBFR' | 'SFCR' | 'OTDR' | 'AHT' | 'IM_DSAT', required
      - `count` integer, nullable: TikTok's own count of orders or returns against the metric. Null means not collected: problem lists are fetched only for POOR/CRITICAL metrics.
      - `truncated` boolean, nullable: True when Reacher stored only part of the list, so the drill-down shows fewer items than ``count``; ``count`` itself is still TikTok's total. False means the stored list was not capped.
      - `approximates` string, required: The Seller Center order counter this is the nearest stand-in for.
      - `drill_down_tool` string
    - `order_counters_available` boolean: Seller Center's order counters (ship within 24h, shipping overdue, cancellation or return requested) — not collected yet.
  - `violations` ReportField, required
    - `available` boolean, required
    - `unavailable_reason` 'region_not_supported' | 'not_synced' | 'no_data_in_window' | 'not_collected' | 'source_unavailable', nullable: Why there is no value: ``region_not_supported`` (TikTok's official Seller Center data is US-only), ``not_synced`` (nothing stored for this shop yet), ``no_data_in_window``, ``not_collected`` (Reacher does not collect this metric yet) or ``source_unavailable`` (a temporary read failure; retry). Null when ``available`` is true.
    - `detail` string, nullable: Plain-language note to relay to the user.
    - `last_updated` string, nullable: Newest stored day behind this field (YYYY-MM-DD), when known.
    - `drill_down_tool` string, nullable: Tool that returns the detail behind this field.
  - `account_health` ReportField, required
    - `available` boolean, required
    - `unavailable_reason` 'region_not_supported' | 'not_synced' | 'no_data_in_window' | 'not_collected' | 'source_unavailable', nullable: Why there is no value: ``region_not_supported`` (TikTok's official Seller Center data is US-only), ``not_synced`` (nothing stored for this shop yet), ``no_data_in_window``, ``not_collected`` (Reacher does not collect this metric yet) or ``source_unavailable`` (a temporary read failure; retry). Null when ``available`` is true.
    - `detail` string, nullable: Plain-language note to relay to the user.
    - `last_updated` string, nullable: Newest stored day behind this field (YYYY-MM-DD), when known.
    - `drill_down_tool` string, nullable: Tool that returns the detail behind this field.
  - `creator_health` CreatorHealthField, required
    - `available` boolean, required
    - `unavailable_reason` 'region_not_supported' | 'not_synced' | 'no_data_in_window' | 'not_collected' | 'source_unavailable', nullable: Why there is no value: ``region_not_supported`` (TikTok's official Seller Center data is US-only), ``not_synced`` (nothing stored for this shop yet), ``no_data_in_window``, ``not_collected`` (Reacher does not collect this metric yet) or ``source_unavailable`` (a temporary read failure; retry). Null when ``available`` is true.
    - `detail` string, nullable: Plain-language note to relay to the user.
    - `last_updated` string, nullable: Newest stored day behind this field (YYYY-MM-DD), when known.
    - `drill_down_tool` string, nullable: Tool that returns the detail behind this field.
    - `definition` 'reacher_derived_v1'
    - `score` integer, nullable: 0-100, Reacher-derived — NOT TikTok's Creator Health rating. Weights 35/25/25/15 over active_ratio, content_rate, gmv_trend and 1-top5_share, re-normalised over the components that are not null.
    - `tier` 'healthy' | 'watch' | 'at_risk', nullable: >=70 healthy, 40-69 watch, <40 at_risk.
    - `components` CreatorHealthComponents
      - `active_ratio` CreatorHealthComponent, required
        - `value` number, nullable: 0-1; null when the denominator is zero.
        - `numerator` number, required
        - `denominator` number, required
      - `content_rate` CreatorHealthComponent, required
        - `value` number, nullable: 0-1; null when the denominator is zero.
        - `numerator` number, required
        - `denominator` number, required
      - `gmv_trend` CreatorHealthComponent, required
        - `value` number, nullable: 0-1; null when the denominator is zero.
        - `numerator` number, required
        - `denominator` number, required
      - `top5_share` CreatorHealthComponent, required
        - `value` number, nullable: 0-1; null when the denominator is zero.
        - `numerator` number, required
        - `denominator` number, required

## Other responses

- `422`: Validation Error

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-10-15** `ae1fba149199`: 4 info
  - added the optional property `creator_health/components` to the response with the `200` status
  - added the optional property `creator_health/definition` to the response with the `200` status
  - added the optional property `creator_health/score` to the response with the `200` status
  - added the optional property `creator_health/tier` to the response with the `200` status
- **2026-10-15** `c97a73893555`: 1 info
  - added the optional property `fulfillment_risk/problem_counts` to the response with the `200` status
- **2026-10-15** `7b2fa05204aa`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/shop-report/snapshot/post.md)

---

[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.dev/reacherapp/apis/reacher-data-api/revisions/63ce74b30b5a?raw)