Match pending samples

curl --request POST \
  --url https://api.growi.io/api/public/v1/tik_tok_shop/samples/match \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "criteria": {
    "maxProductsSampled": {
      "max": 2,
      "withinDays": 90
    },
    "cooldownDays": 90,
    "excludeSampleStates": [
      "content_unfulfilled"
    ],
    "minFollowers": 1000
  },
  "limit": 25,
  "timezone": "America/Los_Angeles"
}
'

import requests

url = "https://api.growi.io/api/public/v1/tik_tok_shop/samples/match"

payload = {
    "criteria": {
        "maxProductsSampled": {
            "max": 2,
            "withinDays": 90
        },
        "cooldownDays": 90,
        "excludeSampleStates": ["content_unfulfilled"],
        "minFollowers": 1000
    },
    "limit": 25,
    "timezone": "America/Los_Angeles"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    criteria: {
      maxProductsSampled: {max: 2, withinDays: 90},
      cooldownDays: 90,
      excludeSampleStates: ['content_unfulfilled'],
      minFollowers: 1000
    },
    limit: 25,
    timezone: 'America/Los_Angeles'
  })
};

fetch('https://api.growi.io/api/public/v1/tik_tok_shop/samples/match', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.growi.io/api/public/v1/tik_tok_shop/samples/match",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'criteria' => [
        'maxProductsSampled' => [
                'max' => 2,
                'withinDays' => 90
        ],
        'cooldownDays' => 90,
        'excludeSampleStates' => [
                'content_unfulfilled'
        ],
        'minFollowers' => 1000
    ],
    'limit' => 25,
    'timezone' => 'America/Los_Angeles'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.growi.io/api/public/v1/tik_tok_shop/samples/match"

	payload := strings.NewReader("{\n  \"criteria\": {\n    \"maxProductsSampled\": {\n      \"max\": 2,\n      \"withinDays\": 90\n    },\n    \"cooldownDays\": 90,\n    \"excludeSampleStates\": [\n      \"content_unfulfilled\"\n    ],\n    \"minFollowers\": 1000\n  },\n  \"limit\": 25,\n  \"timezone\": \"America/Los_Angeles\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.growi.io/api/public/v1/tik_tok_shop/samples/match")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"criteria\": {\n    \"maxProductsSampled\": {\n      \"max\": 2,\n      \"withinDays\": 90\n    },\n    \"cooldownDays\": 90,\n    \"excludeSampleStates\": [\n      \"content_unfulfilled\"\n    ],\n    \"minFollowers\": 1000\n  },\n  \"limit\": 25,\n  \"timezone\": \"America/Los_Angeles\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.growi.io/api/public/v1/tik_tok_shop/samples/match")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"criteria\": {\n    \"maxProductsSampled\": {\n      \"max\": 2,\n      \"withinDays\": 90\n    },\n    \"cooldownDays\": 90,\n    \"excludeSampleStates\": [\n      \"content_unfulfilled\"\n    ],\n    \"minFollowers\": 1000\n  },\n  \"limit\": 25,\n  \"timezone\": \"America/Los_Angeles\"\n}"

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "applicationId": "577000000000000123",
      "creatorId": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg",
      "creatorUsername": "aly.finds.fun",
      "firstSeenAt": "2026-09-28T16:02:11.000Z",
      "products": [
        {
          "productId": "1729400000000000001",
          "productTitle": "Orthopedic dog bed"
        }
      ],
      "creatorPendingApplicationIds": [],
      "lastSeenAt": "2026-09-29T11:40:00.000Z",
      "frontierUnresolved": false,
      "matched": true,
      "criteria": {
        "maxProductsSampled": {
          "result": "pass",
          "value": {
            "count": 1,
            "productIds": [
              "1729400000000000007"
            ],
            "since": "2026-07-01T12:00:00.000Z"
          }
        },
        "cooldownDays": {
          "result": "pass",
          "value": {
            "lastApprovedAt": "2026-05-02T09:14:00.000Z",
            "lastApprovedApplicationId": "577000000000000001",
            "daysSince": 150
          }
        },
        "excludeSampleStates": {
          "result": "pass",
          "value": {
            "applicationIds": []
          }
        },
        "minFollowers": {
          "result": "pass",
          "value": 48210
        }
      }
    }
  ],
  "nextCursor": "WyI1NzcwMDAwMDAwMDAwMDAxMjMiXQ",
  "counts": {
    "scanned": 25,
    "evaluated": 25,
    "matched": 1
  },
  "approvalsToday": {
    "utc": {
      "timezone": "UTC",
      "day": "2026-09-29",
      "from": "2026-09-29T00:00:00.000Z",
      "applications": 14,
      "viaGateway": 9
    },
    "local": {
      "timezone": "America/Los_Angeles",
      "day": "2026-09-29",
      "from": "2026-09-29T07:00:00.000Z",
      "applications": 11,
      "viaGateway": 8
    }
  },
  "note": "Stored data only, no TikTok call. ..."
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

Match pending samples

Checks the shop’s pending sample requests against your criteria and reports which match. It’s read-only: nothing is approved. Requests are scanned roughly oldest first. Send criteria in the JSON body, at least one, and all must pass: minFollowers, maxFollowers, minGmvGlobal30d (platform-wide), categories, minFulfillmentRate, minPostedRate and minPastSampleGmv (this shop), maxProductsSampled, cooldownDays, excludeSampleStates and productIds. Unknown criteria names are rejected.

Each item reports matched and, per criterion, pass, fail or unknown with the value used. unknownAs (fail by default) decides whether unknown blocks a match. include: "all" also returns requests that didn’t match. Narrow the scan with applicationIds.

limit (1 to 50, default 25) caps requests scanned, not matches, so a page can hold zero matches and still have nextCursor. Keep passing nextCursor back as cursor until it’s absent. Requests from the same creator are checked separately; creatorPendingApplicationIds lists the others.

approvalsToday counts today’s approvals for the UTC day and, if you send an IANA timezone, your local day, so you can enforce your own daily cap. Requests Growi can no longer confirm as pending may already be decided on TikTok, so they’re skipped unless includeFrontierUnresolved is true.

POST

tik_tok_shop

samples

match

Match pending samples

curl --request POST \
  --url https://api.growi.io/api/public/v1/tik_tok_shop/samples/match \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "criteria": {
    "maxProductsSampled": {
      "max": 2,
      "withinDays": 90
    },
    "cooldownDays": 90,
    "excludeSampleStates": [
      "content_unfulfilled"
    ],
    "minFollowers": 1000
  },
  "limit": 25,
  "timezone": "America/Los_Angeles"
}
'

import requests

url = "https://api.growi.io/api/public/v1/tik_tok_shop/samples/match"

payload = {
    "criteria": {
        "maxProductsSampled": {
            "max": 2,
            "withinDays": 90
        },
        "cooldownDays": 90,
        "excludeSampleStates": ["content_unfulfilled"],
        "minFollowers": 1000
    },
    "limit": 25,
    "timezone": "America/Los_Angeles"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    criteria: {
      maxProductsSampled: {max: 2, withinDays: 90},
      cooldownDays: 90,
      excludeSampleStates: ['content_unfulfilled'],
      minFollowers: 1000
    },
    limit: 25,
    timezone: 'America/Los_Angeles'
  })
};

fetch('https://api.growi.io/api/public/v1/tik_tok_shop/samples/match', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.growi.io/api/public/v1/tik_tok_shop/samples/match",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'criteria' => [
        'maxProductsSampled' => [
                'max' => 2,
                'withinDays' => 90
        ],
        'cooldownDays' => 90,
        'excludeSampleStates' => [
                'content_unfulfilled'
        ],
        'minFollowers' => 1000
    ],
    'limit' => 25,
    'timezone' => 'America/Los_Angeles'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.growi.io/api/public/v1/tik_tok_shop/samples/match"

	payload := strings.NewReader("{\n  \"criteria\": {\n    \"maxProductsSampled\": {\n      \"max\": 2,\n      \"withinDays\": 90\n    },\n    \"cooldownDays\": 90,\n    \"excludeSampleStates\": [\n      \"content_unfulfilled\"\n    ],\n    \"minFollowers\": 1000\n  },\n  \"limit\": 25,\n  \"timezone\": \"America/Los_Angeles\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.growi.io/api/public/v1/tik_tok_shop/samples/match")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"criteria\": {\n    \"maxProductsSampled\": {\n      \"max\": 2,\n      \"withinDays\": 90\n    },\n    \"cooldownDays\": 90,\n    \"excludeSampleStates\": [\n      \"content_unfulfilled\"\n    ],\n    \"minFollowers\": 1000\n  },\n  \"limit\": 25,\n  \"timezone\": \"America/Los_Angeles\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.growi.io/api/public/v1/tik_tok_shop/samples/match")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"criteria\": {\n    \"maxProductsSampled\": {\n      \"max\": 2,\n      \"withinDays\": 90\n    },\n    \"cooldownDays\": 90,\n    \"excludeSampleStates\": [\n      \"content_unfulfilled\"\n    ],\n    \"minFollowers\": 1000\n  },\n  \"limit\": 25,\n  \"timezone\": \"America/Los_Angeles\"\n}"

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "applicationId": "577000000000000123",
      "creatorId": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg",
      "creatorUsername": "aly.finds.fun",
      "firstSeenAt": "2026-09-28T16:02:11.000Z",
      "products": [
        {
          "productId": "1729400000000000001",
          "productTitle": "Orthopedic dog bed"
        }
      ],
      "creatorPendingApplicationIds": [],
      "lastSeenAt": "2026-09-29T11:40:00.000Z",
      "frontierUnresolved": false,
      "matched": true,
      "criteria": {
        "maxProductsSampled": {
          "result": "pass",
          "value": {
            "count": 1,
            "productIds": [
              "1729400000000000007"
            ],
            "since": "2026-07-01T12:00:00.000Z"
          }
        },
        "cooldownDays": {
          "result": "pass",
          "value": {
            "lastApprovedAt": "2026-05-02T09:14:00.000Z",
            "lastApprovedApplicationId": "577000000000000001",
            "daysSince": 150
          }
        },
        "excludeSampleStates": {
          "result": "pass",
          "value": {
            "applicationIds": []
          }
        },
        "minFollowers": {
          "result": "pass",
          "value": 48210
        }
      }
    }
  ],
  "nextCursor": "WyI1NzcwMDAwMDAwMDAwMDAxMjMiXQ",
  "counts": {
    "scanned": 25,
    "evaluated": 25,
    "matched": 1
  },
  "approvalsToday": {
    "utc": {
      "timezone": "UTC",
      "day": "2026-09-29",
      "from": "2026-09-29T00:00:00.000Z",
      "applications": 14,
      "viaGateway": 9
    },
    "local": {
      "timezone": "America/Los_Angeles",
      "day": "2026-09-29",
      "from": "2026-09-29T07:00:00.000Z",
      "applications": 11,
      "viaGateway": 8
    }
  },
  "note": "Stored data only, no TikTok call. ..."
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

Authorizations

Authorization

string

header

required

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

Query Parameters

organization_id

integer

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

Body

application/json

criteria

object

required

At least one criterion; they AND together. Unknown names are a 400. Names follow the segment vocabulary where one exists (follower_count, gmv_global_30d, fulfillment_rate, sample_state).

Show child attributes

applicationIds

string[]

Check only these requests (the ones still pending).

Required array length: 1 - 50 elements

Pattern: ^\d{1,32}$

limit

integer

default:25

Pending requests scanned per page.

Required range: 1 <= x <= 50

cursor

string

nextCursor from the previous page.

Required string length: 1 - 512

include

enum<string>

default:matched

all also returns the requests that did not match, with the failing criteria.

Available options:

matched,

all

unknownAs

enum<string>

default:fail

Whether an unknown criterion blocks a match. fail follows the segments rule (unknown never matches).

Available options:

fail,

pass

timezone

string

IANA timezone for approvalsToday.local, e.g. America/Los_Angeles.

includeFrontierUnresolved

boolean

default:false

Also include pending requests Growi can no longer confirm as pending (frontierUnresolved). Off by default, since they may already be decided on TikTok.

Response

One page of the scan

items

object[]

required

Show child attributes

counts

object

required

Show child attributes

approvalsToday

object

required

Show child attributes

note

string

required

nextCursor

string

Pass back as cursor. Absent on the last page.

Overview

Conversions

Tracking events

Campaign affiliates

Organization

Applications

Stats

TikTok Shop

Match pending samples

Authorizations

Query Parameters

Body

Response