---
title: "Daily shop GMV time series (Seller Center, full shop view)"
method: POST
path: "/shop-gmv/timeseries"
tags: ["Shop GMV"]
---

# Daily shop GMV time series (Seller Center, full shop view)

`POST /shop-gmv/timeseries`

## Request

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

Daily GMV for one shop from the TikTok Seller Center daily rollup, including channel breakdown (video → affiliate/seller, live → affiliate/seller, product_card → shop_tab/search) and traffic (product impressions/clicks). 

**Differs from POST /metrics/timeseries metric=gmv** — that endpoint reports affiliate-attributed GMV only (Reacher's view of creator-driven sales). This endpoint reports the **total** shop GMV including ads / Smart+ and organic. Use this when the customer wants numbers matching their TikTok Seller Center dashboard. 

Single-shop only — set ``x-shop-id`` to a specific shop ID. Defaults to last 30 days ending yesterday. Max range 90 days (TikTok backfill depth). The newest available day is yesterday; today's row is not returned. Empty ``series`` is a normal 200 response — Seller Center coverage is still rolling out.

## Request body

- ShopGmvTimeseriesRequest: POST /shop-gmv/timeseries request body. Full Seller Center shop GMV (ads + organic + affiliate) — single shop, daily grain.
  - `start_date` string, date, nullable: Inclusive window start (YYYY-MM-DD). Defaults to 29 days before ``end_date`` (30-day window). The Seller Center data is back-filled ~90 days per shop, so older ranges will return an empty series.
  - `end_date` string, date, nullable: Inclusive window end (YYYY-MM-DD). Defaults to yesterday (today is excluded because the daily row is still incomplete).

## Response `200`

Successful Response

- ShopGmvTimeseriesResponse: Daily shop-GMV time series from the Seller Center scrape. Single shop only; ``currency_code`` is per-shop and applies to every point.
  - `shop_id` integer, required
  - `currency` string, nullable: ISO currency code applying to every point in the series (e.g. 'GBP', 'USD'). ``null`` when the series is empty or (defensively) when the source rows somehow mix currencies for the same shop — in that case GMV values should not be summed in the client.
  - `currency_code` string, nullable: Deprecated alias of `currency`; use `currency`.
  - `granularity` string: Always 'daily' in v1.
  - `start_date` string, required
  - `end_date` string, required
  - `series` ShopGmvSeriesPoint[], required: One entry per day with data in the window. Empty when the shop has no Seller Center data for this range (collection is rolling out — empty is a normal, non-error state).
    - `date` string, required: Day (YYYY-MM-DD).
    - `gmv` number, nullable: Total GMV for the day (before tax, excl. platform co-funding). Sum of channels ≈ gmv (small residuals possible).
    - `orders` integer, nullable: Paid orders that day.
    - `items_sold` integer, nullable: Units sold that day.
    - `customers` integer, nullable: Unique paying customers that day.
    - `aov` number, nullable: Average order value for the day.
    - `channels` ShopGmvChannels, required
      - `video` ShopGmvVideoChannel, required: Video-attributed GMV breakdown for a single time point.
        - `gmv` number, nullable: Total video-attributed GMV for the day.
        - `affiliate` number, nullable: Video GMV from creator/affiliate videos.
        - `seller` number, nullable: Video GMV from the seller's own videos.
      - `live` ShopGmvLiveChannel, required: Live-attributed GMV breakdown for a single time point.
        - `gmv` number, nullable: Total live-attributed GMV for the day.
        - `affiliate` number, nullable: Live GMV from creator/affiliate lives.
        - `seller` number, nullable: Live GMV from the seller's own lives.
      - `product_card` ShopGmvProductCardChannel, required: Product-card (organic) GMV breakdown for a single time point.
        - `gmv` number, nullable: Total product-card GMV (organic surfaces).
        - `shop_tab` number, nullable: GMV from customers browsing the shop tab/storefront.
        - `search` number, nullable: GMV from TikTok search results.
    - `traffic` ShopGmvTraffic, required
      - `product_impressions` integer, nullable: Product impressions across surfaces.
      - `product_clicks` integer, nullable: Product clicks across surfaces.

## Other responses

- `422`: Validation Error

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-09-19** `291230805105`: 3 info
  - api operation id `shop_gmv_timeseries_shop_gmv_timeseries_post` removed and replaced with `shop_gmv_timeseries`
  - added the optional property `currency` to the response with the `200` status
  - response property `currency_code` deprecated

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