---
title: "Daily Shop Performance Score (SPS) trend"
method: POST
path: "/shop-health/timeseries"
tags: ["Shop Health"]
---

# Daily Shop Performance Score (SPS) trend

`POST /shop-health/timeseries`

## Request

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

Daily Shop Performance Score for one shop — the same SPS shown in Seller Center (US shops via TikTok's official ``shop_performances/overview`` API, other markets via Seller Center). Each point carries ``sps_score`` (0-5), ``sps_tier``, ``peer_percentile``, and a ``dimensions`` breakdown of the sub-metrics (on-time dispatch, negative-review rate, etc.). 

Single-shop only — set ``x-shop-id`` to a specific shop ID. Defaults to the last 30 days ending yesterday. Max range 90 days. Only shops on the shop-health sync are covered; an empty ``series`` is a normal 200 response (history builds from the first daily pull).

## Request body

- ShopHealthTimeseriesRequest: POST /shop-health/timeseries request body. Daily Shop Performance Score (SPS) trend for one shop.
  - `start_date` string, date, nullable: Inclusive window start (YYYY-MM-DD). Defaults to 29 days before ``end_date`` (30-day window). Max window 90 days.
  - `end_date` string, date, nullable: Inclusive window end (YYYY-MM-DD). Defaults to yesterday (today's snapshot is not recorded until the daily pull runs).

## Response `200`

Successful Response

- ShopHealthTimeseriesResponse: Daily Shop Performance Score (SPS) trend for one shop: TikTok's official shop_performances/overview for US shops, Seller Center for other markets.
  - `shop_id` integer, required
  - `start_date` string, required
  - `end_date` string, required
  - `series` ShopHealthPoint[], required: One entry per day with a recorded snapshot. Empty when the shop has no SPS history for this range (only shops on the shop-health sync are covered, and history builds from the first daily pull — empty is a normal, non-error state).
    - `date` string, nullable: Snapshot day (YYYY-MM-DD).
    - `sps_score` number, nullable: Overall Shop Performance Score, 0-5.
    - `sps_tier` string, nullable: EXCELLENT / GOOD / POOR / CRITICAL / NIL.
    - `peer_percentile` number, nullable: Percentile ranking among peer shops.
    - `dimensions` ShopHealthDimension[]: Per-sub-metric breakdown of the score.
      - `name` string, nullable: Dimension name.
      - `score` number, nullable: Dimension score, 0-5.
      - `status` string, nullable: EXCELLENT / GOOD / POOR / CRITICAL / NIL.
      - `status_text` string, nullable: Localized status label (e.g. 'Excellent').
      - `weight` number, nullable: Percentage weight of this dimension in the overall SPS.

## Other responses

- `422`: Validation Error

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-09-19** `291230805105`: 1 info
  - api operation id `shop_health_timeseries_shop_health_timeseries_post` removed and replaced with `shop_health_timeseries`

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/shop-health/timeseries/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)