TikTok Shop

Use the TikTok Shop connector to sync orders, products, inventory, returns, cancellations, packages, finance statements, payments, withdrawals, and reference data into your Athena lakehouse. This is a Blotout custom connector built on the Airbyte Connector Builder (declarative manifest) with a custom Python component for HMAC-SHA256 request signing.

Prerequisites

• A tag with Blotout Cloud set up (green checkmark in the Tags table)
• A TikTok Shop App Key and App Secret — found in TikTok Shop Partner Center → My Apps
• A Refresh Token (recommended) — obtained by authorizing the app against the seller’s shop. Valid ~365 days; re-authorize before it lapses.
• The shop must have authorized the app via the TikTok authorization URL

Getting the credentials

1. Go to TikTok Shop Partner Center → My Apps → your app → copy App Key and App Secret.
2. Send the seller through the authorization URL: https://auth.tiktok-shops.com/oauth/authorize?app_key=<APP_KEY>&state=<anything>
3. TikTok redirects back with ?code=<auth_code>. Exchange it once for a token pair.
4. Store the refresh_token in the source config.

Create the pipeline

Follow the shared Create a pipeline steps until the source catalogue appears, then select TikTok Shop.

Source configuration

On the Source step, configure the connector:

Field	Purpose
Schedule Type	How the pipeline runs — typically Scheduled
Sync Frequency	How often Airbyte syncs (for example, Every 24 hours)
Source Name	Name for this pipeline — used in the Athena schema <SOURCE_NAME>_<ENV>

Authentication (HMAC-SHA256 signed requests)

TikTok Shop signs every request with HMAC-SHA256 over the path, sorted query params, and body, wrapped in app_secret. Two auth modes are supported:

Mode	Config Fields	When to Use
Refresh token (recommended)	app_key, app_secret, refresh_token	Scheduled syncs. A fresh access token is minted per sync.
Access token	app_key, app_secret, access_token	One-off backfills only. Expires after ~7 days.

If both are set, the refresh token wins.

Configuration fields

Field	Type	Required	Default	Description
app_key	secret string	Yes	—	App key from TikTok Shop Partner Center. Sent as a query param and used in request signing.
app_secret	secret string	Yes	—	App secret. Never transmitted — it is the HMAC-SHA256 key used to sign every request.
refresh_token	secret string	Recommended	—	Refresh token from app authorization. The connector mints a fresh access token per sync. Valid ~365 days.
access_token	secret string	No	—	Alternative to refresh token. Expires after ~7 days — use only for testing or one-off backfills.
shop_cipher	secret string	No	Auto-resolved	Encrypted shop identifier. Leave blank and the connector resolves it automatically. Set explicitly for cross-border sellers with multiple shops.
start_date	string	Yes	—	Earliest date to pull (YYYY-MM-DD), converted to Unix timestamp for the API filters.
end_date	string	No	Now	Latest date to pull (YYYY-MM-DD, inclusive to 23:59:59 UTC). Leave blank for scheduled syncs.
page_size	integer	No	100	Page size for paginated endpoints. TikTok caps most at 100.
lookback_days	integer	No	1	Days to rewind before the stored cursor to catch retroactive changes — status flips, refunds, settlement adjustments (range 1–30).

Supported sync modes

• Incremental Sync — Append (orders, products, returns, cancellations, packages, finance streams)
• Full Refresh (inventory, shops, active_shops, seller_permissions, warehouses, categories, brands, webhooks)

Note

Orders, returns, and settlements mutate after creation. Append plus latest-per-key downstream, or Full Refresh | Overwrite for the small reference streams.

Supported streams

Transactional streams (Incremental)

Stream	Endpoint	Method	Cursor	Sync Window
orders	/order/202309/orders/search	POST	update_time	7 days
products	/product/202309/products/search	POST	update_time	365 days
returns	/return_refund/202309/returns/search	POST	update_time	31 days
cancellations	/return_refund/202309/cancellations/search	POST	update_time	31 days
packages	/fulfillment/202309/packages/search	POST	update_time	31 days
finance_statements	/finance/202309/statements	GET	statement_time	31 days
statement_transactions	/finance/202309/statements/{id}/statement_transactions	GET	Substream	—
finance_payments	/finance/202309/payments	GET	create_time	31 days
finance_withdrawals	/finance/202309/withdrawals	GET	create_time	31 days

Reference streams (Full Refresh)

Stream	Endpoint	Method	Primary Key
inventory	/product/202309/inventory/search	POST	product_id
shops	/authorization/202309/shops	GET	id
active_shops	/seller/202309/shops	GET	id
seller_permissions	/seller/202309/permissions	GET	—
warehouses	/logistics/202309/warehouses	GET	id
categories	/product/202309/categories	GET	id
brands	/product/202309/brands	GET	id
webhooks	/event/202309/webhooks	GET	—

Key stream details

orders — The core stream. Each record nests line_items[], payment{}, recipient_address{}, and packages[]. Unnest downstream in dbt rather than making per-order detail API calls. Key fields include id, status, user_id, buyer_email, fulfillment_type, shipping_provider, tracking_number, warehouse_id, and all SLA timestamps.

products — Product catalog with nested skus[] containing seller_sku, price{}, and inventory[]. Uses inclusive update_time_le filter (unlike other streams that use exclusive _lt).

finance_statements — One statement per seller per day, cut at 00:00 UTC. Contains settlement_amount, revenue_amount, fee_amount, and payment_id. This is the settled-revenue source of truth.

statement_transactions — Substream of finance_statements. Per-order fee, commission, and revenue breakdown including fee_tax_breakdown{} (affiliate commission, platform commission, referral fee, sales tax). The connector stamps statement_id on each record for joins. Enable both finance_statements and statement_transactions on the connection.

Caution

statement_transactions must be Full Refresh | Append in Airbyte. It has no cursor, but its parent is incremental — each run yields only the newest statements’ transactions. Using Overwrite would truncate the fee history.

finance_payments / finance_withdrawals — Payout and bank transfer records. withdrawals requests all four types: WITHDRAW, SETTLE, TRANSFER, REVERSE.

Downstream joins

• orders.id ← returns.order_id, cancellations.order_id, statement_transactions.order_id, packages.orders[].id
• finance_statements.id ← statement_transactions.statement_id
• finance_statements.payment_id → finance_payments.id
• orders.line_items[].product_id → products.id

orders gives GMV; finance_statements / statement_transactions give the settled payout and fee breakdown — that pair makes TikTok Shop contribution margin comparable to other channels in the lakehouse.

Downstream notes

• Schema: tiktok_shop_<client>_prod.*, one table per stream
• All *_time fields are Unix epoch seconds unless stated otherwise
• Deduplication example:

SELECT * FROM (
  SELECT *, ROW_NUMBER() OVER (
    PARTITION BY id
    ORDER BY _airbyte_extracted_at DESC
  ) AS rn
  FROM tiktok_shop_<client>_prod.orders
) WHERE rn = 1

Changelog

Version	Date	Description
1.0.0	2026-08	Initial release with 17 streams: orders, products, inventory, returns, cancellations, packages, finance_statements, statement_transactions, finance_payments, finance_withdrawals, shops, active_shops, seller_permissions, warehouses, categories, brands, webhooks

Complete Schema and Summary

Continue through the Schema and Summary steps to choose streams and confirm the connection. Save and run the first sync.

After a successful sync, Airflow creates an organization-scoped DAG for the pipeline, and dbt models feed downstream analytics.

Related documentation

• Data Pipelines overview — Tags-first create flow