Create TikTok Post
POST/api/tiktok-posting/posts
Creates a TikTok post from a product video or from product photos.
tiktok-posts:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Fields:
- account_id (integer, required unless tiktok_shop_product_id is set): the store's connected TikTok account (List TikTok Accounts by Store)
- store_id (integer, required when account_id is not sent): the store that posts it. A shoppable post (tiktok_shop_product_id set) of a store with a TikTok Shop channel and a connected TikTok Shop official account but no TikTok account sends store_id instead of account_id. When both are sent they must name the same store (422 on store_id otherwise)
- video_id (integer, required for video posts): a product video whose status is ready
- product_id (integer|null, optional): the product the post is about
- caption (string, required): 1–2200 characters, counted in UTF-16 units as TikTok does (an emoji counts as 2)
- mode (string, required): direct (post to the profile) or inbox (send to the creator's TikTok drafts)
- privacy_level (string): who can view the video — PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR or SELF_ONLY. Required for direct, not allowed for inbox. It must be one of the options in Get TikTok Creator Info; there is no default
- allow_comment, allow_duet, allow_stitch (boolean, optional, default false): a setting the creator turned off in TikTok always stays off
- disclose (boolean, optional, default false): commercial content disclosure. When true, brand_organic and/or brand_content must be true
- brand_organic (boolean, optional): "Your brand" — labelled Promotional content
- brand_content (boolean, optional): "Branded content" — labelled Paid partnership; cannot be combined with SELF_ONLY
- is_aigc (boolean, optional, default false): AI-generated content
- publish (string, required): now, schedule, submit (for approval) or draft (kept in SKU.io)
- scheduled_at (ISO-8601 UTC, required when publish=schedule): at least 5 minutes and at most 60 days ahead
- stock_gate_min_units (integer|null, optional, min 1): post only while the product has at least this many sellable units, re-checked at publish time
Photo posts: send media_type=photo instead of a video:
- media_type (string, optional, default video): video or photo. Photo posts are only available once SKU.io's photo address is verified with TikTok (see photo_posts_available in List TikTok Accounts by Store); otherwise 422 "Photo posts aren't available yet"
- video_id: required for video posts; omit or null for photo posts
- photo_image_ids (integer[], required for photo posts): 1–35 distinct product image IDs, in the order they appear on TikTok. When product_id is set they must be that product's images
- photo_cover_index (integer, optional, default 0): which photo (0-based position in photo_image_ids) is the cover
- title (string, optional, photo posts only): up to 90 UTF-16 units
- caption: for a photo post this is TikTok's description, up to 4000 UTF-16 units
- allow_duet / allow_stitch are ignored for photo posts (TikTok has no Duet or Stitch for photos) TikTok fetches the photos itself, then the post follows the same statuses as a video. Changing the photos, their order, the cover or the title clears an approval.
Approval: nothing is sent to TikTok until a person with the tiktok_posts.approve permission has approved this exact post. Posts created with an API token always wait in needs_approval, unless the store's "Allow API posts to skip approval" setting is on (only possible once TikTok has reviewed SKU.io) and the token's owner can approve. From a signed-in session, now/schedule by an approver counts as approval.
Idempotency: send an Idempotency-Key header (required with an API token), 1–128 characters; a longer key is refused with 422 (errors.idempotency_key: "The Idempotency-Key header must be 128 characters or fewer."), never truncated. Repeating a key (same user, same source) returns the original post with 200 and the same body shape instead of creating another (201). The replay is answered before the body is validated, so a retry still gets its post after a time-based rule (e.g. the 5-minute scheduling minimum) would now refuse the same body.
Errors (error_code): account_not_connected, reconnect_needed, scope_missing, video_not_ready (422), validation errors (422).
Scope: tiktok-posts:write. Permission: tiktok_posts.create.
Shoppable video (TikTok Shop product link): send these with a video post when the store's TikTok Shop official account is connected (see Get Store Shoppable Video Status):
- tiktok_shop_product_id (string of digits, optional, max 64): a product from Search TikTok Shop Products for Shoppable Videos. Send null on update to make the post a normal TikTok post again
- anchor_title (string, required with a product): the text on the product link, up to 30 letters or numbers; punctuation and emoji are removed
- shoppable_public_confirmed (boolean, required true unless publish=draft): shoppable videos post publicly through TikTok Shop, with no privacy, comment, Duet, Stitch or disclosure settings A shoppable post is always a video posted to the profile (mode direct); privacy_level is not needed. Videos over 10 MB are refused (422 shoppable_video_too_large). Before posting, TikTok Shop checks the video and product link; a failed check fails the post with TikTok Shop's reasons. Changing the product or anchor title clears an approval. The post carries publish_channel (content_posting or shoppable), tiktok_shop_product_id, anchor_title, shop_video_id, shop_precheck_status and shop_precheck_issues.
Request
Responses
- 200
- 201
- 401
- 403
- 422
- 429
OK
Response Headers
Created
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.