This API is provided for sellers to query sample applications based on various criteria such as products, creators, or application statuses. By using this API, sellers can retrieve detailed information about sample application records, including the creator’s information and the specifics of each application.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Identifies the shop. Obtain it from the Get Authorized Shops API.
Pagination offset determines where you begin to search for. It’s empty when raise your first request.
The value of “page_size” must be greater than 0 and less than or equal to 50.
Request Body
Section titled “Request Body”object
The unique identifier of a product. It is used to specify which product’s sample application details are being queried.
Product name, supports fuzzy search queries. It allows sellers to search for products by name when managing sample applications.
The creator’s Open ID. Do not use a user ID, creator ID, or seller ID. Send this property as creator_user_oepn_id exactly as spelled; do not change the wire key to creator_user_open_id.
TikTok User Name of a creator, supports fuzzy search
The unique ID generated after creating a target collaboration. Send this property as target_collabration_id exactly as spelled; do not change the wire key to target_collaboration_id.
Main order ID associated with a sample order when the sample application is approved by seller.
The status of sample applications. The possible enumerated values are:
- PENDING: The sample application is waiting for the seller’s review.
- AWAITING_SHIPMENT: The application is approved, and the seller needs to ship the sample.
- SHIPPED: The sample has been shipped by the seller and is waiting for the creator to receive the package.
- CONTENT_PENDING: The creator has received the sample package and is expected to create content.
- REJECT_CANCELLED: The sample application has been rejected by the seller.
- OVERDUE_CANCELLED: The sample application has expired due to being overdue.
- UNFULFILL_CANCELLED: The creator did not fulfill the commitment to create content within the agreed timeframe.
- DEL_OPEN_COLLAB: Open collaboration has been deleted.
- SELLER_NOT_SHIP_CANCELLED: The seller did not ship the sample within the required timeframe.
- WITHDRAW_CANCELLED: The creator withdrew the sample application before the seller approved it.
- UNFULFILLABLE_CANCELLED: The application was cancelled due to reasons beyond the creator’s control, making it impossible to create content.
- OPS_CANCELLED: The application was manually cancelled by operations staff.
- OPS_FAILED: The application was marked as failed by operations staff.
- OPS_COMPLETED: The application was manually marked as completed by operations staff.
- COMPLETED: The application is complete, and the creator has posted the content. This field allows for tracking the status of a sample application throughout its lifecycle, providing visibility into each stage of the process for sellers and creators.
Example
{ "product_id": "123456", "title": "product name", "creator_user_oepn_id": "123456", "username": "test_tt_name", "target_collabration_id": "123456", "order_id": "123456", "status": "PENDING"}Responses
Section titled “Responses”Success
object
Status code; 0 means success.
Success or failure message.
Request log ID.
object
The pagination token to pass as page_token in the next request. Reuse the same page_size for each subsequent page. An empty string indicates that there are no more pages.
Total count
The sample applications from creators
object
The unique id of sample request application ID
The commission rate set by the merchant for creators for this product, represented as a decimal fraction with two decimal places. For example, 0.20 represents 20%. The range is [0.01, 0.8].
The status of sample applications. The possible enumerated values are:
- PENDING: The sample application is waiting for the seller’s review.
- AWAITING_SHIPMENT: The application is approved, and the seller needs to ship the sample.
- SHIPPED: The sample has been shipped by the seller and is waiting for the creator to receive the package.
- CONTENT_PENDING: The creator has received the sample package and is expected to create content.
- REJECT_CANCELLED: The sample application has been rejected by the seller.
- OVERDUE_CANCELLED: The sample application has expired due to being overdue.
- UNFULFILL_CANCELLED: The creator did not fulfill the commitment to create content within the agreed timeframe.
- DEL_OPEN_COLLAB: The open collaboration plan has been deleted.
- SELLER_NOT_SHIP_CANCELLED: The seller did not ship the sample within the required timeframe.
- WITHDRAW_CANCELLED: The creator withdrew the sample application before the seller approved it.
- UNFULFILLABLE_CANCELLED: The application was cancelled due to reasons beyond the creator’s control, making it impossible to create content.
- OPS_CANCELLED: The application was manually cancelled by operations staff.
- OPS_FAILED: The application was marked as failed by operations staff.
- OPS_COMPLETED: The application was manually marked as completed by operations staff.
- COMPLETED: The application is complete, and the creator has finished creating the content.
The sample order is generated after the sample application is approved by seller
The remaining stock quota of a sample product.
The seller approval deadline for the sample application, expressed as a Unix timestamp in seconds.
The deadline for the seller to ship the sample for the application, expressed as a Unix timestamp in seconds.
The logistics tracking number for the sample application order
It indicates the current status of the fulfillment process. The possible values are:
- PENDING: The creator is yet to fulfill the content creation obligation.
- ONGOING: Fulfillment is in progress; content has been created and is being evaluated against criteria.
- SUCCEED: Fulfillment has been successfully completed; the content meets the required standards.
- FAILED: Fulfillment failed; the content did not meet the required standards.
- OVERDUE: Fulfillment is overdue; the creator did not meet the deadline.
- SUSPEND: Fulfillment has been suspended.
- CANCELLED: Fulfillment has been cancelled, either by the creator or due to operational reasons.
- EXEMPTED: The creator has been exempted from the fulfillment obligation.
The sample application can be approved or not.
Reasons the sample application cannot be approved. This list may be absent or empty even when is_approvable is false; always check is_approvable to determine whether approval is allowed.
The name of the partner if the sample application is submitted on behalf of a creator by an agency. It is only populated when an agency handles the application process instead of the creator directly.
Creator details, including the creator’s TikTok username, Creator Open ID, profile information, and e-commerce performance metrics such as sales and fulfillment rates.
object
Creator Open ID. More details
TikTok User Name of a creator
TikTok Nick Name of a creator
The number of creator’s followers
The URL of the creator’s avatar image
GMV generated by a creators’ shoppable content over the past 30 days. It is formatted as a floating-point number with a currency symbol (e.g., “$1234.56”). If the creator has not authorized the disclosure of this information, the field returns an empty string.
object
GMV amount in the corresponding currency.
GMV currency code (ISO 4217 standard). If LOCAL currency is requested, the value will be the local currency code of where the shop is registered (e.g. GBP).
The number of contents a creator has posted in the last 30 days. It is formatted as an integer. If the creator has not authorized the sharing of this information, the field returns an empty string.
The creator’s sample fulfillment rate over the past 90 days, returned as a percentage string with no percent sign (for example, 60.85). If the creator has not authorized disclosure of this information, the field returns an empty string.
The median number of creators’ shoppable video views over the past 30 days. If the creator has not authorized the sharing of this information, the field returns an empty string.
Product information
object
The product identifier.
The product name of the product.
The unique id of product sku which creator apply for as sample.
The URL of SKU image.
The SKU property value names, joined by commas.
Example
{ "code": 0, "data": { "next_page_token": "b2Zmc2V0PTUw", "total_count": 100, "sample_applications": [ { "id": "123456", "commission_rate": "0.20", "status": "PENDING", "order_id": "123456", "available_quantity": 50, "approve_expiration_time": 1728674995, "shipment_expiration_time": 1728674995, "tracking_number": "123456", "fulfillment_status": "ONGOING", "is_approvable": true, "disapprovable_reasons": [ "Product out of stock" ], "partner_name": "ABC", "creator": { "creator_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "username": "test.name", "nickname": "Test Name", "follower_count": 200, "avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068xxxxx", "gmv": { "amount": "500", "currency": "USD" }, "content_count": 4, "fulfillment_percentage": "60.50", "ec_video_view": 1200 }, "product": { "id": "123456", "title": "A women dress", "sku_id": "123456", "sku_image_url": "https://p16-oec-va.ibyteimg.com/tos-malivaxxxxx", "sku_name": "Soft Cover" } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7"}