> ## 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 by Product

> One row per creator with an embedded products[] array breaking their GMV down by product for the date range. Ordered by total GMV descending (no sort parameter).

Lists creators with a per-product breakdown of their TikTok Shop sales — one row per creator with an embedded `products[]` array showing how their GMV splits across products for the requested date range. This is the same data as the **Products** tab (Creators view) of the TikTok Shop store page.

For the product-level rollup, see [TikTok Shop Products](/api-reference/endpoint/get-tik-tok-shop-store-products).

## Response Fields

Each creator row contains:

| Field                                                                          | Type           | Description                                           |
| ------------------------------------------------------------------------------ | -------------- | ----------------------------------------------------- |
| `id`                                                                           | Integer        | Internal row id                                       |
| `external_id`                                                                  | String         | TikTok creator id (oecuid)                            |
| `affiliate_id` / `affiliate_name` / `affiliate_email` / `affiliate_avatar_url` | Mixed          | Growi creator info (`"N/A"` / null when not on Growi) |
| `connected_account`                                                            | Object         | `{ id, username, profile_share_url }`                 |
| `product_count`                                                                | Integer        | Distinct products this creator sold                   |
| `latest_date`                                                                  | String \| null | Most recent date with sales                           |
| `total_gmv`                                                                    | Number         | GMV in display currency units                         |
| `total_units_sold` / `total_sku_orders` / `total_items_refunded`               | Integer        | Sales counts                                          |
| `total_commission` / `total_refunded_amount` / `total_estimated_flat_fee`      | Number         | Money totals                                          |
| `products`                                                                     | Array          | Per-product breakdown, GMV descending (fields below)  |
| `*_formatted`                                                                  | String         | Display-string variant of every metric above          |

Each entry in `products[]` contains `external_product_id`, `product_name`, `product_image_url`, `latest_date`, plus the same raw + `*_formatted` metric pairs (`total_gmv`, `total_units_sold`, `total_sku_orders`, `total_commission`, `total_refunded_amount`, `total_items_refunded`, `total_estimated_flat_fee`).

The response envelope is `{ data, meta, additional_data }`; `meta` additionally includes `page_size`.

## 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                             | 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       | —       |
| `platform`         | String  | `growi` or `all`                                        | No       | `growi` |
| `product_id`       | String  | Only include creators who sold this TikTok Shop product | 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                          | No       | —       |

## Request Example

```bash theme={null}
curl -X GET "https://api.growi.io/api/public/v1/tik_tok_shop/product_creators?start_date=2026-07-01&end_date=2026-07-31&product_id=1729548090545311965" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY" \
     -H "Content-Type: application/json"
```

## Response Example

```json theme={null}
{
  "data": [
    {
      "id": 771122,
      "external_id": "7495033444...",
      "affiliate_id": 98765,
      "affiliate_name": "Jane Creator",
      "connected_account": {
        "id": 4321,
        "username": "janecreates",
        "profile_share_url": "https://www.tiktok.com/@janecreates"
      },
      "product_count": 3,
      "latest_date": "2026-07-29",
      "total_gmv": 20000.0,
      "total_gmv_formatted": "$20,000.00",
      "total_units_sold": 640,
      "total_units_sold_formatted": "640",
      "products": [
        {
          "external_product_id": "1729548090545311965",
          "product_name": "Peach Perfect Multivitamin",
          "product_image_url": "https://...",
          "latest_date": "2026-07-29",
          "total_gmv": 15000.0,
          "total_gmv_formatted": "$15,000.00",
          "total_units_sold": 480,
          "total_units_sold_formatted": "480"
        }
      ]
    }
  ],
  "meta": {
    "row_count": 210,
    "total_pages": 11,
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "page_size": 20
  },
  "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

* Answering "who sold this product?" with `product_id`
* Building creator × product performance matrices
* Structuring product-seeding decisions around which creators move which SKUs
* Reconciling per-product commissions per creator

## Notes

* Results are always ordered by total GMV descending; there is no sort parameter.
* Without a `product_id` filter, the listing also includes tracked creators with zero sales in the range (matching the dashboard's row counts); with `product_id`, only creators who sold that product are returned.
* 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/product_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/product_creators:
    get:
      summary: TikTok Shop Creators by Product
      description: >-
        One row per creator with an embedded products[] array breaking their GMV
        down by product for the date range. Ordered by total GMV descending (no
        sort parameter).
      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: 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
        - name: product_id
          in: query
          required: false
          schema:
            type: string
          description: Only include creators who sold this TikTok Shop product id
      responses:
        '200':
          description: Product creators listed
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TikTokShopStoreProductCreatorRow'
                  meta:
                    allOf:
                      - $ref: '#/components/schemas/TikTokShopStoreMeta'
                      - type: object
                        properties:
                          page_size:
                            type: integer
                            description: Rows on this page
                  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:
    TikTokShopStoreProductCreatorRow:
      type: object
      properties:
        id:
          type: integer
        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
        product_count:
          type: integer
        latest_date:
          type: string
          nullable: true
        products:
          type: array
          description: Per-product breakdown for this creator, GMV descending
          items:
            type: object
            properties:
              external_product_id:
                type: string
              product_name:
                type: string
                nullable: true
              product_image_url:
                type: string
                nullable: true
              latest_date:
                type: string
                nullable: true
              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_estimated_flat_fee:
                type: number
                description: Raw amount in display currency units (e.g. dollars)
              total_estimated_flat_fee_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
        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_estimated_flat_fee:
          type: number
          description: Raw amount in display currency units (e.g. dollars)
        total_estimated_flat_fee_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
    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

````