> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# TikTok Shop as a data source
> Bring data from TikTok Shop to your Lakehouse.
TikTok Shop is TikTok's e-commerce marketplace, where sellers list products and fulfill orders placed through in-feed videos, LIVE sessions, the product showcase and the Shop tab. The TikTok Shop Partner Open API gives access to a seller's shop data, including orders, product catalog, stock, settlement statements, returns, packages and promotions.
## Configuring TikTok Shop as a Source
In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the TikTok Shop option from the list of connectors.
Click **Next** and you'll be prompted to add your access.
### 1. Add account access
You'll need to authorize Nekt to access your TikTok Shop data. You don't need to register anything in the TikTok Shop Partner Center — Nekt already has an approved app there, and you simply grant it access to your shop.
Click on the **Authorization** button. You'll be redirected to TikTok Shop, where you need to be signed in to the Seller Center account that owns the shop you want to sync. There you'll:
1. Confirm the **shop** the authorization applies to, choose the **access duration** (we recommend *Unlimited*, so the connection doesn't stop working on a fixed date) and enter a **contact email**, then click **Confirm installation**.
2. Review the permissions Nekt is requesting — product, order, logistics and finance information — accept the acknowledgement and click **Authorize**.
You'll be redirected back to Nekt with the connection filled in automatically. If you ever need to reconnect the shop, use the **Refresh** button next to the field.
The following configurations are also available:
* **Start Date**: The earliest date from which records will be synced. If not provided, all available historical data will be extracted.
The following advanced settings are also available:
* **Shop cipher**: The encrypted identifier of a single shop. Leave it empty to sync every shop the authorization covers — the connector resolves the shops automatically.
* **Shop ID**: The shop identifier reported alongside the records. Only used when a shop cipher is set manually.
Don't have access to the TikTok Shop account yourself? Use the **Share link** option at the top of this step to send the authorization to whoever manages the shop — they complete it without needing a Nekt account.
Once you're done, click **Next**.
### 2. Select streams
Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.
> Tip: The stream can be found more easily by typing its name.
Select the streams and click **Next**.
### 3. Configure data streams
Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.
* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
* Incremental: every time the extraction happens, we'll get only the new data - which is good if, for example, you want to keep every record ever fetched.
* Full table: every time the extraction happens, we'll get the current state of the data - which is good if, for example, you don't want to have deleted data in your catalog.
Once you are done configuring, click **Next**.
### 4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters.
To define your [Trigger](https://docs.nekt.com/get-started/core-concepts/triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).
Optionally, you can define some additional settings:
* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
Once you are ready, click **Next** to finalize the setup.
### 5. Check your new source
You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.
## Good to know
* **Multiple shops**: a single authorization can cover more than one shop. Every record carries a `shop_id` column identifying which shop it came from, and the `shops` stream lists the shops the authorization reaches.
* **Timestamps**: TikTok Shop returns dates as Unix timestamps in seconds (UTC), so fields such as `create_time` and `update_time` are integers.
* **Amounts**: monetary values arrive as strings in the shop's currency, preserving the exact value returned by TikTok Shop.
* **Nested data**: fields that contain nested structures — such as the order payment breakdown or the product SKUs — are stored as JSON strings, so they stay stable as TikTok Shop adds new subfields.
* **Rate limits**: TikTok Shop allocates request capacity dynamically per app and shop. When the platform throttles a request, the connector waits and retries automatically, which can make an extraction take longer.
# Streams and Fields
Below you'll find all available data streams from TikTok Shop and their corresponding fields:
The shops the connected authorization gives access to. Useful to map `shop_id` values to shop names and regions.
**Key Fields:**
* `id` - Unique identifier of the shop
* `name` - Display name of the shop
* `region` - Market the shop sells in (e.g. BR, US, ID)
* `seller_type` - Whether the seller is local to the region or cross-border
* `cipher` - Encrypted shop identifier used by shop-scoped endpoints
* `code` - Short shop code used by TikTok Shop
Orders placed in the shop, with their status timeline, buyer information, fulfillment data and full payment breakdown. Synced incrementally by `update_time`.
**Identification:**
* `id` - TikTok Shop order identifier
* `shop_id` - Shop the order belongs to
* `status` - Order status (UNPAID, ON\_HOLD, AWAITING\_SHIPMENT, PARTIALLY\_SHIPPING, AWAITING\_COLLECTION, IN\_TRANSIT, DELIVERED, COMPLETED, CANCELLED)
* `order_type` - Order type, such as a regular order or a pre-order
* `commerce_platform` - Platform where the order was placed
**Timeline (Unix timestamps):**
* `create_time` - When the order was placed
* `update_time` - Last change to the order, used as the incremental replication key
* `paid_time` - When the order was paid
* `rts_time` - When the seller marked the order ready to ship
* `collection_time` - When the carrier collected the package
* `delivery_time` - When the package was delivered
* `cancel_time` - When the order was cancelled
* `rts_sla_time`, `tts_sla_time`, `delivery_sla_time` - Platform deadlines for shipping, collection and delivery
* `shipping_due_time`, `collection_due_time`, `delivery_due_time` - Due dates for each fulfillment step
* `cancel_order_sla_time` - When the platform automatically cancels the order
* `pick_up_cut_off_time`, `fast_dispatch_sla_time`, `recommended_shipping_time`, `release_date`
**Buyer:**
* `user_id` - TikTok user identifier of the buyer
* `buyer_email` - Email address of the buyer
* `buyer_nickname`, `buyer_avatar` - Public TikTok profile of the buyer
* `buyer_message` - Note left by the buyer at checkout
* `seller_note` - Internal note added by the seller
* `cpf`, `cpf_name` - Buyer tax identifier used to issue an invoice (Brazil)
**Fulfillment:**
* `fulfillment_type` - FULFILLMENT\_BY\_SELLER, FULFILLMENT\_BY\_TIKTOK or FULFILLMENT\_BY\_DILAYANI\_TOKOPEDIA
* `delivery_type` - HOME\_DELIVERY or COLLECTION\_POINT
* `shipping_type` - TIKTOK, SELLER or TIKTOK\_DIGITAL
* `shipping_provider`, `shipping_provider_id` - Carrier handling the order
* `tracking_number` - Carrier tracking number
* `delivery_option_id`, `delivery_option_name` - Delivery option chosen by the buyer
* `warehouse_id` - Warehouse serving the order
* `fast_delivery_program`, `fulfillment_priority_level`
**Cancellation and exceptions:**
* `cancellation_initiator` - SELLER, BUYER or SYSTEM
* `cancel_reason` - Reason the order was cancelled
* `is_buyer_request_cancel` - Whether the buyer asked to cancel
* `is_on_hold_order`, `has_updated_recipient_address`, `authentication_required`
* `is_replacement_order`, `replaced_order_id`, `is_exchange_order`, `exchange_source_order_id`
* `is_sample_order`, `is_refundable_sample`, `is_subscription_order`
* `split_or_combine_tag`, `auto_combine_group_id`
* `need_upload_invoice`, `consultation_id`
**Payment:**
* `payment_method_name` - Payment method used by the buyer
* `is_cod` - Whether the buyer pays cash on delivery
* `payment` - JSON object with the full payment breakdown: `currency`, `sub_total`, `shipping_fee`, `seller_discount`, `platform_discount`, `tax`, `total_amount` and the market-specific fees
**Nested data (JSON strings):**
* `line_items` - Products, quantities, prices, discounts and taxes of the order
* `packages` - Packages the order was split into
* `recipient_address` - Delivery address (not available while the order is UNPAID or ON\_HOLD)
* `handling_duration` - Handling time agreed for the order
* `order_rights` - Order tags from the programs the seller subscribes to
Products listed in the shop, with their SKUs, prices and stock. Synced incrementally by `update_time`.
**Key Fields:**
* `id` - TikTok Shop product identifier
* `shop_id` - Shop the product belongs to
* `title` - Product title shown to buyers
* `status` - Listing status (DRAFT, PENDING, FAILED, ACTIVATE, SELLER\_DEACTIVATED, PLATFORM\_DEACTIVATED, FREEZE, DELETED)
* `create_time` - When the product was created
* `update_time` - Last change to the product, used as the incremental replication key
* `is_not_for_sale` - Whether the product is flagged as not available for sale
* `has_draft` - Whether the product has unpublished draft changes
* `listing_quality_tier` - Quality tier TikTok Shop assigns to the listing content
**Nested data (JSON strings):**
* `skus` - SKUs with seller SKU, price, stock per warehouse, status and fees
* `sales_regions` - Regions where the product is sold
* `recommended_categories` - Categories TikTok Shop recommends for the product
* `integrated_platform_statuses` - Status on natively integrated platforms, such as Tokopedia
* `audit` - Audit status of the product and the reasons behind it
* `product_families` - Product families the product belongs to
* `scheduled_sale` - Scheduled sale configuration
* `product_sync_fail_reasons` - Why syncing the global product to this listing failed
Available and committed stock per SKU and warehouse.
**Key Fields:**
* `product_id` - TikTok Shop product identifier
* `shop_id` - Shop the product belongs to
* `skus` - JSON array with the stock of each SKU, broken down by warehouse and by campaign, creator and in-shop allocation
Settlement statements, that is, the payouts TikTok Shop transfers to the seller. Synced incrementally by `statement_time`.
**Key Fields:**
* `id` - Settlement statement identifier
* `shop_id` - Shop the statement belongs to
* `statement_time` - When the statement was generated, used as the incremental replication key
* `payment_time` - When the payout was transferred to the seller
* `payment_status` - Whether the payout already reached the seller's bank account
* `payment_id` - Identifier of the payout transfer
* `currency` - Currency of every amount in the statement
**Amounts:**
* `settlement_amount` - Net amount settled to the seller
* `revenue_amount` - Gross revenue included in the statement
* `net_sales_amount` - Revenue after seller-funded discounts
* `fee_amount` - Total platform fees deducted
* `shipping_cost_amount` - Total shipping costs
* `adjustment_amount` - Total adjustments applied by TikTok Shop policy
The individual transactions that make up each settlement statement, which is where order-level revenue, fees and shipping costs can be reconciled.
**Key Fields:**
* `id` - Transaction identifier
* `statement_id` - Settlement statement the transaction belongs to
* `shop_id` - Shop the transaction belongs to
* `type` - Transaction type, such as an order settlement or an adjustment
* `order_id` - Order the transaction settles
* `order_create_time` - When the settled order was placed
* `currency` - Currency of every amount in the transaction
**Amounts:**
* `settlement_amount` - Net amount settled for the transaction
* `revenue_amount` - Revenue recognized in the transaction
* `shipping_cost_amount` - Shipping cost charged to the seller
* `fee_tax_amount` - Taxes charged on the platform fees
* `adjustment_amount`, `adjustment_id`, `adjustment_order_id` - Adjustment details
* `reserve_id`, `reserve_amount`, `reserve_status`, `estimated_release_time` - Funds withheld under the reserve policy
* `associated_order_id` - Order associated with a reserve or adjustment entry
**Nested data (JSON strings):**
* `revenue_breakdown` - Detailed revenue components
* `shipping_cost_breakdown` - Detailed shipping cost components
* `fee_tax_breakdown` - Detailed fee tax components
* `supplementary_component` - Additional settlement components
Withdrawals and transfers made from the TikTok Shop balance. Synced incrementally by `create_time`.
**Key Fields:**
* `id` - Withdrawal identifier
* `shop_id` - Shop the withdrawal belongs to
* `type` - Withdrawal type, such as a settlement transfer or a manual withdrawal
* `amount` - Amount withdrawn
* `currency` - Currency of the withdrawal
* `status` - Current status of the withdrawal
* `create_time` - When the withdrawal was created, used as the incremental replication key
Return and refund requests opened against the shop's orders. Synced incrementally by `update_time`.
**Key Fields:**
* `return_id` - Return request identifier
* `shop_id` - Shop the return belongs to
* `order_id` - Order the return was opened against
* `return_type` - Type of the request (refund, return and refund, replacement)
* `return_status` - Current status of the request
* `arbitration_status` - Status of the platform arbitration, when escalated
* `role` - Who initiated the return
* `return_reason`, `return_reason_text` - Reason for the return
* `create_time` - When the request was opened
* `update_time` - Last change to the request, used as the incremental replication key
**Logistics:**
* `shipment_type` - How the buyer sends the items back
* `handover_method` - Handover method chosen by the buyer
* `return_tracking_number` - Tracking number of the return shipment
* `return_provider_name`, `return_provider_id` - Carrier handling the return
* `return_shipping_document_type` - Type of return shipping document
* `return_method` - Method used to return the items
**Resolution:**
* `can_buyer_keep_item` - Whether the buyer may keep the item and still be refunded
* `is_quick_refund` - Whether the buyer was refunded before the items were received
* `seller_proposed_return_type` - Return type the seller proposed instead
* `buyer_rejected_partial_refund` - Whether the buyer rejected the proposed partial refund
* `is_combined_return`, `combined_return_id` - Whether the return was combined with others
* `pre_return_id`, `next_return_id` - Related return requests
**Nested data (JSON strings):**
* `return_line_items` - Items covered by the return, with refund amounts
* `refund_amount` - Refund breakdown of the request
* `discount_amount` - Discounts reverted by the return
* `shipping_fee_amount` - Shipping fees involved in the return
* `partial_refund` - Partial refund proposed for the return
* `return_warehouse_address` - Address the items must be returned to
* `seller_next_action_response` - Actions the seller must take and their deadlines
Order cancellation requests raised by buyers, sellers or the platform. Synced incrementally by `update_time`.
**Key Fields:**
* `cancel_id` - Cancellation request identifier
* `shop_id` - Shop the cancellation belongs to
* `order_id` - Order the cancellation refers to
* `cancel_type` - Type of the cancellation request
* `cancel_status` - Current status of the request
* `role` - Who initiated the cancellation
* `cancel_reason`, `cancel_reason_text` - Reason for the cancellation
* `should_replenish_stock` - Whether the cancelled items return to available stock
* `create_time` - When the cancellation was requested
* `update_time` - Last change to the cancellation, used as the incremental replication key
**Nested data (JSON strings):**
* `cancel_line_items` - Items covered by the cancellation, with refund amounts
* `refund_amount` - Refund breakdown of the cancellation
* `seller_next_action_response` - Actions the seller must take and their deadlines
Packages created to fulfill the shop's orders. Synced incrementally by `update_time`.
**Key Fields:**
* `id` - Package identifier
* `shop_id` - Shop the package belongs to
* `status` - Current status of the package
* `create_time` - When the package was created
* `update_time` - Last change to the package, used as the incremental replication key
* `tracking_number` - Carrier tracking number
* `shipping_provider_name`, `shipping_provider_id` - Carrier handling the package
* `orders` - JSON array with the orders and SKUs contained in the package
* `order_line_item_ids` - JSON array with the order line items contained in the package
Promotion activities configured in the shop, such as flash sales and direct discounts.
**Key Fields:**
* `id` - Promotion activity identifier
* `shop_id` - Shop the activity belongs to
* `title` - Title of the promotion activity
* `activity_type` - Type of promotion (FLASHSALE, DIRECT\_DISCOUNT, SHIPPING\_DISCOUNT, BUY\_MORE\_SAVE\_MORE, GIFT\_WITH\_PURCHASE)
* `duration_type` - Whether the activity runs for a fixed period or is open ended
* `status` - Current status of the activity
* `product_level` - Whether the promotion applies at product or variation level
* `begin_time`, `end_time` - When the promotion starts and ends
* `create_time`, `update_time` - When the promotion was created and last changed
**Nested data (JSON strings):**
* `discount` - Discount rules of the activity
* `participation_limit` - Limits on how many times a buyer can use the promotion
* `activity_commands` - Operations currently allowed on the activity
Coupons created by the shop.
**Key Fields:**
* `id` - Coupon identifier
* `shop_id` - Shop the coupon belongs to
* `title` - Title of the coupon
* `display_type` - Where the coupon is shown to buyers
* `status` - Current status of the coupon
* `promo_code` - Code buyers enter to redeem the coupon
* `target_buyer_segment` - Buyer segment the coupon targets
* `product_scope` - Range of products the coupon applies to
* `creation_source` - System where the coupon was created
* `create_time`, `update_time` - When the coupon was created and last changed
**Nested data (JSON strings):**
* `claim_duration` - Period during which buyers can claim the coupon
* `redemption_duration` - Period during which a claimed coupon can be redeemed
* `usage_limits` - Claim and redemption limits
* `discount` - Discount granted by the coupon
* `threshold` - Minimum purchase required to use the coupon
Warehouses registered by the shop for pickup and returns.
**Key Fields:**
* `id` - Warehouse identifier
* `shop_id` - Shop the warehouse belongs to
* `name` - Name of the warehouse
* `entity_id` - Legal entity the warehouse belongs to
* `effect_status` - Whether the warehouse is currently in effect
* `type` - Warehouse purpose, such as sales or return warehouse
* `sub_type` - More specific warehouse classification
* `is_default` - Whether this is the default warehouse for its type
* `address` - JSON object with the full warehouse address, including geolocation