> ## 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. # 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. ## OpenAPI ````yaml api-reference/tik-tok-shop-openapi.json POST /tik_tok_shop/samples/match openapi: 3.0.3 info: title: 'Growi API: TikTok Shop' version: 1.0.0 description: >- Generated by scripts/gen_tik_tok_shop.rb from Growi's TikTok Shop route table. servers: - url: https://api.growi.io/api/public/v1 security: - bearerAuth: [] paths: /tik_tok_shop/samples/match: post: summary: Match pending samples description: >- 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. parameters: - name: organization_id in: query required: false schema: type: integer description: >- Use the TikTok Shop of this child brand (organization id) of your API key's organization requestBody: required: true content: application/json: schema: type: object required: - criteria additionalProperties: false properties: criteria: type: object additionalProperties: false minProperties: 1 description: >- 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). properties: minFollowers: type: integer minimum: 0 description: >- Creator follower count (identity row, from the samples API creator block) at least this. maxFollowers: type: integer minimum: 0 description: >- Follower count at most this. Must not be below minFollowers. minGmvGlobal30d: type: object additionalProperties: false required: - amount properties: amount: type: string pattern: ^\d{1,15}(\.\d{1,6})?$ description: Decimal string, compared exactly (never as a float). currency: type: string pattern: ^[A-Z]{3}$ description: >- Optional. When set, a stored value in another currency is unknown, not compared (a stored zero passes in any currency). When omitted, the amount is compared as is, whatever currency the stored value is in. description: >- Creator's GMV from shoppable content over the past 30 days, platform-wide (all shops), as TikTok's samples API reports it in the creator block (affiliate_seller Search Sample Applications, creator.gmv). Not this shop's GMV. categories: type: array minItems: 1 maxItems: 50 items: type: string minLength: 1 maxLength: 64 description: >- TikTok category ids. Passes when the creator's stored categories (marketplace enrichment) include any of them. unknown when the creator was never enriched. minFulfillmentRate: type: number minimum: 0 maximum: 100 description: >- TikTok's 90-day sample fulfillment rate, percent, platform-wide (samples API creator.fulfillment_percentage). minPostedRate: type: number minimum: 0 maximum: 1 description: >- This shop only: the creator's posted rate over their OTHER applications here (content_fulfilled / shipped, as /samples/vetting history.postedRate). unknown when nothing was shipped yet. minPastSampleGmv: type: object additionalProperties: false required: - amount properties: amount: type: string pattern: ^\d{1,15}(\.\d{1,6})?$ description: Decimal string, compared exactly (never as a float). currency: type: string pattern: ^[A-Z]{3}$ description: >- Optional. When set, a stored value in another currency is unknown, not compared (a stored zero passes in any currency). When omitted, the amount is compared as is, whatever currency the stored value is in. description: >- This shop only, lifetime: GMV from affiliate_orders attributed to the creator's OTHER samples here by the /samples/outcomes rule (an order line on one of the sample's videos, for a product it requested, under the creator's handle; INELIGIBLE lines excluded). unknown when there is nothing to join on (no stored content or handle) or currencies mix. maxProductsSampled: type: object additionalProperties: false required: - max - withinDays properties: max: type: integer minimum: 0 maximum: 1000 withinDays: type: integer minimum: 1 maximum: 3650 description: >- Distinct products approved for the creator in this shop in the last withinDays days, at most max. Counts the creator's OTHER applications only, not the one being checked (to cap the total at 2 including a one-product request, send max 1). Approved = the application reached awaiting_shipment or later; its approval time is the earliest such stamp, and a request cancelled after approval still counts. cooldownDays: type: integer minimum: 1 maximum: 3650 description: >- Passes when the creator's last approved sample in this shop (other applications) is at least this many days old, or there is none. excludeSampleStates: type: array minItems: 1 items: type: string enum: - sample_requested - awaiting_shipment - sample_shipped - content_pending - content_warning - content_fulfilled - content_unfulfilled - cancelled description: >- Fails when any of the creator's OTHER applications in this shop has a row currently in one of these states, e.g. ["content_unfulfilled"] to skip creators who never posted for a past sample. productIds: type: array minItems: 1 maxItems: 100 items: type: string pattern: ^\d{1,32}$ description: >- Only requests for one of these products. Also narrows the scan in SQL, so every returned item passes it. applicationIds: type: array minItems: 1 maxItems: 50 items: type: string pattern: ^\d{1,32}$ description: Check only these requests (the ones still pending). limit: type: integer minimum: 1 maximum: 50 default: 25 description: Pending requests scanned per page. cursor: type: string description: nextCursor from the previous page. minLength: 1 maxLength: 512 include: type: string enum: - matched - all default: matched description: >- all also returns the requests that did not match, with the failing criteria. unknownAs: type: string enum: - fail - pass default: fail description: >- Whether an unknown criterion blocks a match. fail follows the segments rule (unknown never matches). timezone: type: string description: >- IANA timezone for approvalsToday.local, e.g. America/Los_Angeles. includeFrontierUnresolved: type: boolean default: false description: >- Also include pending requests Growi can no longer confirm as pending (frontierUnresolved). Off by default, since they may already be decided on TikTok. example: criteria: maxProductsSampled: max: 2 withinDays: 90 cooldownDays: 90 excludeSampleStates: - content_unfulfilled minFollowers: 1000 limit: 25 timezone: America/Los_Angeles responses: '200': description: One page of the scan content: application/json: schema: type: object required: - items - counts - approvalsToday - note properties: items: type: array items: type: object required: - applicationId - creatorId - creatorUsername - firstSeenAt - products - creatorPendingApplicationIds - lastSeenAt - frontierUnresolved - matched - criteria properties: applicationId: type: string creatorId: type: string description: Creator open id. creatorUsername: type: string nullable: true firstSeenAt: type: string format: date-time description: When Growi first saw the request. products: type: array items: type: object properties: productId: type: string nullable: true productTitle: type: string nullable: true creatorPendingApplicationIds: type: array items: type: string description: >- The creator's other requests in this shop still awaiting review. lastSeenAt: type: string format: date-time description: >- When Growi last saw the request, from a sync or a TikTok notification. frontierUnresolved: type: boolean description: >- Growi no longer sees it as pending and couldn't find its current state, so the stored state may be out of date. Only true when includeFrontierUnresolved was sent. matched: type: boolean description: >- Every criterion passed (with unknownAs pass, unknown counts as passing). criteria: type: object description: >- Only the criteria you sent, each with its result and the stored value used. properties: minFollowers: type: object required: - result - value properties: result: type: string enum: - pass - fail - unknown description: >- unknown = the stored value is missing (not synced, not shared by the creator, no history in this shop) or not comparable. value: description: Follower count. type: number nullable: true maxFollowers: type: object required: - result - value properties: result: type: string enum: - pass - fail - unknown description: >- unknown = the stored value is missing (not synced, not shared by the creator, no history in this shop) or not comparable. value: description: Follower count. type: number nullable: true minGmvGlobal30d: type: object required: - result - value properties: result: type: string enum: - pass - fail - unknown description: >- unknown = the stored value is missing (not synced, not shared by the creator, no history in this shop) or not comparable. value: description: '{amount, currency} as stored.' categories: type: object required: - result - value properties: result: type: string enum: - pass - fail - unknown description: >- unknown = the stored value is missing (not synced, not shared by the creator, no history in this shop) or not comparable. value: description: >- The creator's category ids, null if never enriched. minFulfillmentRate: type: object required: - result - value properties: result: type: string enum: - pass - fail - unknown description: >- unknown = the stored value is missing (not synced, not shared by the creator, no history in this shop) or not comparable. value: description: Percent. type: number nullable: true minPostedRate: type: object required: - result - value properties: result: type: string enum: - pass - fail - unknown description: >- unknown = the stored value is missing (not synced, not shared by the creator, no history in this shop) or not comparable. value: description: >- {postedRate, shipped, contentFulfilled} over the other applications. minPastSampleGmv: type: object required: - result - value properties: result: type: string enum: - pass - fail - unknown description: >- unknown = the stored value is missing (not synced, not shared by the creator, no history in this shop) or not comparable. value: description: '{amount, currency, orders}, or null.' maxProductsSampled: type: object required: - result - value properties: result: type: string enum: - pass - fail - unknown description: >- unknown = the stored value is missing (not synced, not shared by the creator, no history in this shop) or not comparable. value: description: '{count, productIds, since}.' cooldownDays: type: object required: - result - value properties: result: type: string enum: - pass - fail - unknown description: >- unknown = the stored value is missing (not synced, not shared by the creator, no history in this shop) or not comparable. value: description: >- {lastApprovedAt, lastApprovedApplicationId, daysSince}. excludeSampleStates: type: object required: - result - value properties: result: type: string enum: - pass - fail - unknown description: >- unknown = the stored value is missing (not synced, not shared by the creator, no history in this shop) or not comparable. value: description: '{applicationIds} that hit.' productIds: type: object required: - result - value properties: result: type: string enum: - pass - fail - unknown description: >- unknown = the stored value is missing (not synced, not shared by the creator, no history in this shop) or not comparable. value: description: >- The requested product ids that are in your list. nextCursor: type: string description: Pass back as cursor. Absent on the last page. counts: type: object required: - scanned - evaluated - matched properties: scanned: type: integer description: >- Pending requests the page read (before any are dropped). evaluated: type: integer description: >- Of those, the ones still pending once loaded and checked against the criteria (a sibling row can already be past review). matched: type: integer approvalsToday: type: object required: - utc - local properties: utc: type: object required: - timezone - day - from - applications - viaGateway properties: timezone: type: string description: UTC, or the timezone the caller sent. day: type: string format: date description: The calendar day in that timezone. from: type: string format: date-time description: When that day started, UTC. applications: type: integer description: >- Distinct applications Growi saw approved (moved to awaiting_shipment) at or after `from`, whoever approved them. viaGateway: type: integer description: Of those, the ones approved through Growi. local: type: object required: - timezone - day - from - applications - viaGateway properties: timezone: type: string description: UTC, or the timezone the caller sent. day: type: string format: date description: The calendar day in that timezone. from: type: string format: date-time description: When that day started, UTC. applications: type: integer description: >- Distinct applications Growi saw approved (moved to awaiting_shipment) at or after `from`, whoever approved them. viaGateway: type: integer description: Of those, the ones approved through Growi. nullable: true note: type: string example: 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. ... '400': description: >- Invalid body: an unknown criterion or key, no criteria, minFollowers over maxFollowers, a bad state, timezone or cursor; also a body that is not a valid JSON object content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '403': description: Read-only (viewer) API keys can't call POST endpoints content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '404': description: >- `organization_id` isn't an active child brand of your organization, or the record you asked for doesn't exist content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '422': description: >- No TikTok Shop is connected for this organization. A parent organization whose shops sit on its child brands has to pass `organization_id` content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '429': description: >- Rate limited: one call every 2 seconds and an hourly cap per API key. See `Retry-After` and the `X-RateLimit-*` headers content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '502': description: >- TikTok refused or failed. `error` is a fixed message and `code` names the failure when there is one content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' components: schemas: TikTokShopError: type: object required: - error properties: error: type: string description: What went wrong code: type: string description: Machine-readable reason, when there is one securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.