Sample funnel

Returns the sample funnel for a cohort of sample requests: counts per stage, conversion rates and time in stage. The cohort is every sample row (one per application and product) first seen as requested between start_date and end_date (YYYY-MM-DD, UTC, inclusive, at most 365 days apart). Later stages count for that cohort whenever they happened.

Stages run sample_requested, awaiting_shipment, sample_shipped, content_pending, content_fulfilled. Each has count, rateFromPrevious and rateFromRequested (fractions, 0.6 = 60%, null when the denominator is 0) and timeInStage (median and p90 hours to the next stage). exits counts content_warning and content_unfulfilled (set by Growi’s timers) and cancelled (set by TikTok). byCollabType splits open and target collabs, and currentStates counts rows by state. Filter with productId or targetCollaborationId.

Times are when Growi observed each change, not TikTok’s event times. For a newly connected shop, its whole pending backlog lands on the day it connected.

GET /tik_tok_shop/samples/funnel

Sample funnel

cURL

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

200

{
  "shopId": "7494000000000000900",
  "window": {
    "startDate": "2026-01-01",
    "endDate": "2026-01-31"
  },
  "filters": {
    "productId": null,
    "targetCollaborationId": null
  },
  "cohort": 200,
  "stages": [
    {
      "key": "sample_requested",
      "count": 200,
      "source": "tts_native",
      "rateFromPrevious": null,
      "rateFromRequested": 1,
      "timeInStage": {
        "medianHours": 20.5,
        "p90Hours": 70.1,
        "rows": 150
      }
    },
    {
      "key": "awaiting_shipment",
      "count": 150,
      "source": "tts_native",
      "rateFromPrevious": 0.75,
      "rateFromRequested": 0.75,
      "timeInStage": {
        "medianHours": 30,
        "p90Hours": 96,
        "rows": 120
      }
    },
    {
      "key": "sample_shipped",
      "count": 120,
      "source": "tts_native",
      "rateFromPrevious": 0.8,
      "rateFromRequested": 0.6,
      "timeInStage": {
        "medianHours": 72,
        "p90Hours": 150,
        "rows": 100
      }
    },
    {
      "key": "content_pending",
      "count": 100,
      "source": "tts_native",
      "rateFromPrevious": 0.8333,
      "rateFromRequested": 0.5,
      "timeInStage": {
        "medianHours": 120,
        "p90Hours": 300,
        "rows": 60
      }
    },
    {
      "key": "content_fulfilled",
      "count": 60,
      "source": "tts_native",
      "rateFromPrevious": 0.6,
      "rateFromRequested": 0.3,
      "timeInStage": null
    }
  ],
  "exits": [
    {
      "key": "content_warning",
      "count": 12,
      "source": "timer",
      "rateFromRequested": 0.06
    },
    {
      "key": "content_unfulfilled",
      "count": 8,
      "source": "timer",
      "rateFromRequested": 0.04
    },
    {
      "key": "cancelled",
      "count": 30,
      "source": "tts_native",
      "rateFromRequested": 0.15
    }
  ],
  "byCollabType": {
    "open": {
      "requested": 150,
      "approved": 110,
      "shipped": 90,
      "contentFulfilled": 40
    },
    "target": {
      "requested": 50,
      "approved": 40,
      "shipped": 30,
      "contentFulfilled": 20
    }
  },
  "currentStates": {
    "content_fulfilled": 60,
    "content_pending": 32,
    "cancelled": 30,
    "sample_requested": 50,
    "awaiting_shipment": 20,
    "content_unfulfilled": 8
  }
}

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

Cohort window start, YYYY-MM-DD (UTC) INCLUSIVE.

end_date · string · required

Cohort window end, YYYY-MM-DD (UTC) INCLUSIVE. At most 365 days after start_date.

productId · string

Only this product's sample rows.

targetCollaborationId · string

Only samples attributed to this target collaboration.

organization_id · integer

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

Response

200

application/json

{ shopId, window {startDate, endDate}, filters {productId, targetCollaborationId}, cohort, stages: [{ key, count, source: "tts_native", rateFromPrevious, rateFromRequested, timeInStage: { medianHours, p90Hours, rows } | null }], exits: [{ key, count, source: "timer" | "tts_native", rateFromRequested }], byCollabType: { open, target } each { requested, approved, shipped, contentFulfilled }, currentStates: { state: count } }. Rates are fractions (0.6 = 60%) to 4 dp, null when the denominator is 0.