---
title: "Shop sales series (GMV, orders, units, visitors, conversion rate)"
method: POST
path: "/shop-performance/timeseries"
tags: ["Shop Performance"]
---

# Shop sales series (GMV, orders, units, visitors, conversion rate)

`POST /shop-performance/timeseries`

## Request

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

Daily or weekly (Sunday-start) sales for one shop from TikTok's official Seller Center analytics. Each bucket says how many days it covers and whether it is complete, so a partial current week is never mistaken for a decline. Window: a preset (``7d``, ``30d``, ``90d``, ``12m``, ``all``) ending at the shop's newest stored day, or explicit ``start_date``/``end_date``; max 365 days. Single-shop only. An empty ``points`` list is a normal 200 for shops the collector does not cover yet.

## Request body

- SeriesRequest: Body for the two shop-performance series endpoints.
  - `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).
  - `granularity` 'day' | 'week': ``day`` returns one point per day; ``week`` sums Sunday-start weeks.

## Response `200`

Successful Response

- ShopPerformanceSeriesResponse
  - `shop_id` integer, required
  - `currency_code` string, nullable: Null when the window mixes currencies; points carry their own.
  - `start_date` string, required
  - `end_date` string, required
  - `granularity` 'day' | 'week', required
  - `week_start` 'sunday'
  - `latest_available_date` string, nullable: Newest stored day for this shop, or null when nothing is stored.
  - `earliest_available_date` string, nullable: Oldest stored day for this shop, or null when nothing is stored. A prior-period comparison is only meaningful when the prior window starts on or after this day.
  - `is_complete` boolean, required
  - `points` ShopPerformancePoint[], required
    - `date` string, required: Bucket start (YYYY-MM-DD).
    - `date_end` string, required: Bucket end, inclusive (YYYY-MM-DD).
    - `days_expected` integer, required: Days of this bucket inside the window and on or before the settled day.
    - `days_observed` integer, required: Days with a stored row.
    - `is_complete` boolean, required: True only when the whole bucket is settled, every expected day has a row, and no core metric is missing on any of them.
    - `currency_code` string, nullable: ISO 4217 currency code. ``USD`` when present — the official TikTok API normalises all amounts to US dollars. ``null`` when the window has no data.
    - `gmv` number, nullable
    - `video_attributed_gmv` number, nullable
    - `live_attributed_gmv` number, nullable
    - `product_card_gmv` number, nullable
    - `gross_revenue` number, nullable
    - `refunds` number, nullable
    - `orders` integer, nullable: Unique checkout orders (one per transaction, regardless of how many SKUs are in the cart). Compare with ``sku_orders`` for the per-product line count.
    - `sku_orders` integer, nullable
    - `items_sold` integer, nullable
    - `customers` integer, nullable: Buyers per day as TikTok reports them; weekly buckets sum the days, so a repeat buyer counts each day.
    - `page_views` integer, nullable
    - `visitors` integer, nullable
    - `conversion_rate` number, nullable: Ratio, e.g. 0.0389. Weekly = orders / visitors.

## Other responses

- `422`: Validation Error

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-09-09** `a5d66477ac03`: 1 info
  - endpoint added

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