> ## Documentation Index > Fetch the complete documentation index at: https://growi.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # TikTok Shop Creators > One row per creator with GMV, orders, commission, and refund totals for the date range. Ordered by total GMV descending (no sort parameter). Money fields are raw numbers in display currency units with *_formatted display-string variants. Lists creator performance for your TikTok Shop — one row per creator with GMV, units sold, orders, commission, and refund totals for the requested date range. This is the same data as the **Creators** tab of the TikTok Shop store page, with every filter the dashboard offers. ## Response Fields Each creator row contains: | Field | Type | Description | | ------------------------------------------- | --------------- | ------------------------------------------------------------------ | | `id` | Integer \| null | Internal snapshot id | | `external_id` | String | TikTok creator id (oecuid) | | `affiliate_id` | Integer \| null | Growi user id (null if the creator is not on Growi) | | `affiliate_name` | String | Creator name (`"N/A"` when unknown) | | `affiliate_email` | String | Creator email (`"N/A"` when unknown) | | `affiliate_avatar_url` | String | Avatar image URL | | `connected_account` | Object | `{ id, username, profile_share_url }` of the linked TikTok account | | `total_gmv` | Number | Gross merchandise value in display currency units (e.g. dollars) | | `total_units_sold` | Integer | Items sold | | `total_sku_orders` | Integer | SKU orders | | `total_commission` | Number | Estimated commission | | `total_refunded_amount` | Number | Refunded amount | | `total_items_refunded` | Integer | Items refunded | | `total_posts_with_gmv` | Integer | Distinct videos with GMV in the range | | `total_live_gmv` / `total_product_card_gmv` | Number | Always `0` (reserved) | | `*_formatted` | String | Display-string variant of every metric above (e.g. `"$1,234.56"`) | The response envelope is `{ data, meta, additional_data }`: `meta` carries pagination (`row_count`, `total_pages`, `current_page`, `next_page`, `prev_page`) and `additional_data` carries raw totals across the full result set plus `currency` / `currency_symbol`. ## Request Parameters | Parameter | Type | Description | Required | Default | | ---------------------- | ------- | --------------------------------------------------------------------------------------------------- | -------- | ------- | | `start_date` | String | Start of the GMV date range (ISO 8601, `YYYY-MM-DD`) | Yes | — | | `end_date` | String | End of the GMV date range (ISO 8601, `YYYY-MM-DD`) | Yes | — | | `page` | Integer | Page number | No | 1 | | `per_page` | Integer | Results per page (max 100) | No | 20 | | `search` | String | Free-text search by creator name | No | — | | `campaign_id` | Integer | Filter to a campaign or contract in your organization | No | — | | `creator_id` | Integer | Filter to a single Growi creator (user id) | No | — | | `external_creator_id` | String | Filter to a single TikTok creator (oecuid) | No | — | | `connected_account_id` | Integer | Filter by connected social account id | No | — | | `platform` | String | `growi` (only creators on Growi), `all` (all TikTok Shop data), `non_growi` (creators not on Growi) | No | `growi` | | `gmv_min` / `gmv_max` | Number | GMV range bounds in display currency units | No | — | | `all_contracts` | String | `'true'` to include creators from all contracts | No | — | | `exclude_contests` | String | `'true'` to exclude TikTok Shop contest campaigns | No | — | | `organization_id` | Integer | Narrow to a child organization of the API key organization | No | — | ## Request Example ```bash theme={null} curl -X GET "https://api.growi.io/api/public/v1/tik_tok_shop/creators?start_date=2026-07-01&end_date=2026-07-31&platform=all&per_page=20" \ -H "Authorization: Bearer YOUR_PUBLIC_API_KEY" \ -H "Content-Type: application/json" ``` ## Response Example ```json theme={null} { "data": [ { "id": 123456, "external_id": "7495033444...", "affiliate_id": 98765, "affiliate_name": "Jane Creator", "affiliate_email": "jane@example.com", "affiliate_avatar_url": "https://...", "connected_account": { "id": 4321, "username": "janecreates", "profile_share_url": "https://www.tiktok.com/@janecreates" }, "total_gmv": 12345.67, "total_gmv_formatted": "$12,345.67", "total_units_sold": 480, "total_units_sold_formatted": "480", "total_sku_orders": 402, "total_sku_orders_formatted": "402", "total_commission": 1851.85, "total_commission_formatted": "$1,851.85", "total_refunded_amount": 250.0, "total_refunded_amount_formatted": "$250.00", "total_items_refunded": 12, "total_items_refunded_formatted": "12", "total_posts_with_gmv": 35, "total_posts_with_gmv_formatted": "35" } ], "meta": { "row_count": 214, "total_pages": 11, "current_page": 1, "next_page": 2, "prev_page": null }, "additional_data": { "total_gmv": 250000.5, "total_units_sold": 10400, "total_sku_orders": 9020, "total_commission": 37500.25, "total_items_refunded": 310, "total_refunded_amount": 6100.0, "currency_symbol": "$", "currency": "usd" } } ``` ## Use Cases * Building creator leaderboards and performance dashboards from your TikTok Shop data * Reconciling creator commissions against GMV for payout workflows * Comparing on-Growi vs. off-Growi creator performance via the `platform` filter * Tracking campaign- or contract-specific creator performance with `campaign_id` ## Notes * Results are always ordered by total GMV descending; there is no sort parameter. * Money fields are raw numbers in display currency units (dollars for USD shops); use the `*_formatted` variants for display. * Dates are inclusive; the dashboard's default view is the last 30 days. * Requests are rate limited (minimum 2 seconds between requests plus an hourly quota); see the `X-RateLimit-*` response headers. ## OpenAPI ````yaml GET /tik_tok_shop/creators openapi: 3.0.1 info: title: Growi API description: >- API documentation for Growi platform, showcasing the public tracking event endpoint license: name: MIT version: 1.0.0 servers: - url: https://api.growi.io/api/public/v1 security: - bearerAuth: [] paths: /tik_tok_shop/creators: get: summary: TikTok Shop Creators description: >- One row per creator with GMV, orders, commission, and refund totals for the date range. Ordered by total GMV descending (no sort parameter). Money fields are raw numbers in display currency units with *_formatted display-string variants. parameters: - name: start_date in: query required: true schema: type: string format: date description: Start of the GMV date range (ISO 8601, YYYY-MM-DD) example: '2026-07-01' - name: end_date in: query required: true schema: type: string format: date description: End of the GMV date range (ISO 8601, YYYY-MM-DD) example: '2026-07-31' - name: page in: query required: false schema: type: integer default: 1 description: Page number (default 1) - name: per_page in: query required: false schema: type: integer default: 20 maximum: 100 description: 'Results per page: 1-100, default 20' - name: search in: query required: false schema: type: string description: Free-text search - name: campaign_id in: query required: false schema: type: integer description: Filter to a campaign or contract belonging to your organization - name: creator_id in: query required: false schema: type: integer description: Filter to a single Growi creator (user id) - name: platform in: query required: false schema: type: string enum: - growi - all - non_growi default: growi description: >- Data scope: growi (only creators on Growi, default), all (all TikTok Shop data), non_growi (creators not on Growi) - name: organization_id in: query required: false schema: type: integer description: >- Narrow results to a child organization (id) of the API key organization - name: external_creator_id in: query required: false schema: type: string description: Filter to a single TikTok creator by TikTok creator id (oecuid) - name: connected_account_id in: query required: false schema: type: integer description: >- Filter by connected social account id (matches dashboard behavior; prefer external_creator_id) - name: gmv_min in: query required: false schema: type: number description: Minimum GMV in display currency units (e.g. dollars) - name: gmv_max in: query required: false schema: type: number description: Maximum GMV in display currency units (e.g. dollars) - name: all_contracts in: query required: false schema: type: string enum: - 'true' description: Set to 'true' to include creators from all contracts - name: exclude_contests in: query required: false schema: type: string enum: - 'true' description: Set to 'true' to exclude TikTok Shop contest campaigns responses: '200': description: Creators listed content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/TikTokShopStoreCreatorRow' meta: $ref: '#/components/schemas/TikTokShopStoreMeta' additional_data: $ref: '#/components/schemas/TikTokShopStoreTotals' required: - data - meta - additional_data '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- Invalid parameters (missing/invalid dates, unknown platform or linked value, foreign campaign_id, no TikTok Shop connected) content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: TikTokShopStoreCreatorRow: type: object properties: id: type: integer nullable: true external_id: type: string description: TikTok creator id (oecuid) connected_account: type: object properties: id: type: integer nullable: true username: type: string profile_share_url: type: string affiliate_id: type: integer nullable: true description: Growi user id (null if the creator is not on Growi) affiliate_name: type: string affiliate_email: type: string affiliate_avatar_url: type: string total_gmv: type: number description: Raw amount in display currency units (e.g. dollars) total_gmv_formatted: type: string description: Display string (e.g. "$1,234.56") total_commission: type: number description: Raw amount in display currency units (e.g. dollars) total_commission_formatted: type: string description: Display string (e.g. "$1,234.56") total_refunded_amount: type: number description: Raw amount in display currency units (e.g. dollars) total_refunded_amount_formatted: type: string description: Display string (e.g. "$1,234.56") total_live_gmv: type: number description: Raw amount in display currency units (e.g. dollars) total_live_gmv_formatted: type: string description: Display string (e.g. "$1,234.56") total_product_card_gmv: type: number description: Raw amount in display currency units (e.g. dollars) total_product_card_gmv_formatted: type: string description: Display string (e.g. "$1,234.56") total_units_sold: type: integer total_units_sold_formatted: type: string total_sku_orders: type: integer total_sku_orders_formatted: type: string total_items_refunded: type: integer total_items_refunded_formatted: type: string total_posts_with_gmv: type: integer total_posts_with_gmv_formatted: type: string TikTokShopStoreMeta: type: object description: Pagination metadata properties: row_count: type: integer description: Total rows across all pages total_pages: type: integer current_page: type: integer next_page: type: integer nullable: true prev_page: type: integer nullable: true TikTokShopStoreTotals: type: object description: Raw totals across the full (unpaginated) result set properties: total_gmv: type: number total_units_sold: type: integer total_sku_orders: type: integer total_commission: type: number total_items_refunded: type: integer total_refunded_amount: type: number currency_symbol: type: string currency: type: string nullable: true Error: required: - error - message type: object properties: error: type: string message: type: string securitySchemes: bearerAuth: type: http scheme: bearer ````