Creator activity over time

Returns active, new, returning, retained and churned creators per week or month. A creator is active in a period when they have a counting affiliate sale for this shop (INELIGIBLE lines excluded). new means their first sale ever falls in the period. returning means active, not active in the previous period, and not new. retained means active in this period and the previous one. churned means active in the previous period but not this one, and carries the previous period’s GMV and orders. Each group has creators, gmvGross and orders.

granularity is week (Monday to Sunday, default) or month, both in UTC. start_date and end_date are inclusive, at most 365 days apart. Every period touching the window is returned; a clipped first or last period has partial: true, so start on a Monday or the 1st to avoid that. historyFrom is the earliest sale Growi holds, so periods near it can count long-standing creators as new.

GET /tik_tok_shop/affiliate/creator_activity

Creator activity over time

cURL

curl --request GET \
  --url https://api.growi.io/api/public/v1/tik_tok_shop/affiliate/creator_activity \
  --header 'Authorization: Bearer <token>'

200

{
  "window": {
    "startDate": "2026-08-31",
    "endDate": "2026-09-13"
  },
  "sweptThrough": "2026-09-28T06:00:00.000Z",
  "granularity": "week",
  "timezone": "UTC",
  "historyFrom": "2025-11-02",
  "currency": "USD",
  "periods": [
    {
      "period": "2026-08-31",
      "from": "2026-08-31",
      "to": "2026-09-06",
      "partial": false,
      "active": {
        "creators": 20,
        "gmvGross": 2580.75,
        "orders": 86
      },
      "new": {
        "creators": 5,
        "gmvGross": 300,
        "orders": 10
      },
      "returning": {
        "creators": 3,
        "gmvGross": 180.5,
        "orders": 6
      },
      "retained": {
        "creators": 12,
        "gmvGross": 2100.25,
        "orders": 70
      },
      "churned": {
        "creators": 4,
        "gmvGross": 220,
        "orders": 8
      }
    },
    {
      "period": "2026-09-07",
      "from": "2026-09-07",
      "to": "2026-09-13",
      "partial": false,
      "active": {
        "creators": 22,
        "gmvGross": 2955,
        "orders": 97
      },
      "new": {
        "creators": 6,
        "gmvGross": 410,
        "orders": 13
      },
      "returning": {
        "creators": 2,
        "gmvGross": 95,
        "orders": 3
      },
      "retained": {
        "creators": 14,
        "gmvGross": 2450,
        "orders": 81
      },
      "churned": {
        "creators": 6,
        "gmvGross": 340.5,
        "orders": 12
      }
    }
  ],
  "source": "rollup",
  "note": "Periods are calendar weeks (Monday start) or months in UTC, the same day buckets as every /affiliate read; the first and last are clipped to the window (partial: true). A creator is active in a period when they have a counting sale in it for this shop (gross affiliate GMV, INELIGIBLE lines excluded, keyed by open id like /affiliate/creators, with rollup days stored before we knew the open id merged in). new: their first counting sale ever falls in the period. returning: active, not active in the previous period, not new. retained: active in this period and the previous one. So active = new + returning + retained. churned: active in the previous period, not in this one; its GMV and orders are the previous period's. The first period's previous period is the whole calendar period before it, even when that falls outside the window. 'Ever' means every row we hold: historyFrom is the earliest counting creator sale we hold on or before end_date, and our rows only start at the shop's first orders sweep, so periods near it overcount new creators."
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

start_date · string · required

Window start, YYYY-MM-DD INCLUSIVE, UTC day of the order create time. Start on a Monday or a 1st to avoid a clipped first period.

end_date · string · required

Window end, YYYY-MM-DD INCLUSIVE. At most 365 days after start_date, same cap as the other affiliate reads.

granularity · enum<string> · default: week

week (Monday to Sunday, UTC) or month (calendar month, UTC).

Available options: week, month

organization_id · integer

Use the TikTok Shop of this child brand (organization id) of your API key's organization

Response

200

application/json

{ window, sweptThrough, granularity, timezone: UTC, historyFrom (earliest counting creator sale we hold on or before end_date; null when there is none), currency (null when mixed or empty), periods: [{ period (calendar start), from, to, partial, active, new, returning, retained, churned }] with each group { creators, gmvGross, orders }, source: rollup | live, note }.