> For the complete documentation index, see [llms.txt](https://help.daasity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.daasity.com/core-concepts/data-integrations/setup-guides/digital-integrations/tiktok-shop/integration-specifications.md). # Integration Specifications ### Integration Overview TikTok Shop is TikTok's native ecommerce platform, enabling merchants to sell products directly within the TikTok app. Daasity's TikTok Shop integration connects directly to the TikTok Shop API to replicate transactional order data — orders, payments, line items, pricing, discounts, returns, and refunds. This document provides context on what kind of data is being gathered through this extractor, which endpoints that data is coming from, and how the extracted tables relate to each other. ### Integration Availability This integration is currently in **Beta** and is enabled per-account by Daasity. It is not part of the standard integration set on any plan — contact your Account Manager to have it enabled. ### API Endpoints The Daasity TikTok Shop extractor is built based on the TikTok Shop Partner API. The following endpoints are used by Daasity to replicate data from TikTok Shop: * Authorized Shops — `GET /authorization/202309/shops` (identifies the authorized shop at setup; does not create a table) * Order List — `POST /order/202309/orders/search` * Order Price Detail — `GET /order/202407/orders/{order_id}/price_detail` * External Orders — `GET /order/202406/orders/{order_id}/external_orders` * Returns — `POST /return_refund/202309/returns/search` * Products — `POST /product/202502/products/search` * Coupons — `POST /promotion/202406/coupons/search` * Activities — `POST /promotion/202309/activities/search` * Shop Performance — `GET /analytics/202509/shop/performance` * Shop Product Performance — `GET /analytics/202509/shop_products/{product_id}/performance` {% hint style="info" %} Payment data is not a separate endpoint — it is parsed from the `payment` object embedded in the Order List response and lands in `order_payments`. Order Price Detail and External Orders are fetched per order (one API call per order ID) as children of the Orders sync; External Orders is only retrieved when the integration is configured with external platforms. {% endhint %} #### Entity Relationship Diagram (ERD) An ERD for the TikTok Shop integration is not yet available. ### TikTok Shop Schema The Daasity TikTok Shop extractor creates these tables using the endpoints and replication methods listed. All tables are stored in the `tiktok_shop` schema, are upserted on `__sync_key`, and carry Daasity housekeeping columns (`_account_id`, `__synced_at`, `__source_id`, `__shop_id`) in addition to the columns listed below. **Order tables** * [Orders](https://claude.ai/chat/8c3f96ff-b0d1-4cae-960c-2d2cd305c9b0#orders) * [Order Payments](https://claude.ai/chat/8c3f96ff-b0d1-4cae-960c-2d2cd305c9b0#order-payments) * [Order Line Items](https://claude.ai/chat/8c3f96ff-b0d1-4cae-960c-2d2cd305c9b0#order-line-items) * [Order Line Item Combined SKUs](https://claude.ai/chat/8c3f96ff-b0d1-4cae-960c-2d2cd305c9b0#order-line-item-combined-skus) * [Order Price Detail](https://claude.ai/chat/8c3f96ff-b0d1-4cae-960c-2d2cd305c9b0#order-price-detail) * [Order Line Item Price Detail](https://claude.ai/chat/8c3f96ff-b0d1-4cae-960c-2d2cd305c9b0#order-line-item-price-detail) * [External Orders](https://claude.ai/chat/8c3f96ff-b0d1-4cae-960c-2d2cd305c9b0#external-orders) * [Returns](https://claude.ai/chat/8c3f96ff-b0d1-4cae-960c-2d2cd305c9b0#returns) * [Return Line Items](https://claude.ai/chat/8c3f96ff-b0d1-4cae-960c-2d2cd305c9b0#return-line-items) **Non-order tables** * [Products and related tables](https://claude.ai/chat/8c3f96ff-b0d1-4cae-960c-2d2cd305c9b0#non-order-tables) * [Coupons](https://claude.ai/chat/8c3f96ff-b0d1-4cae-960c-2d2cd305c9b0#non-order-tables) * [Activities](https://claude.ai/chat/8c3f96ff-b0d1-4cae-960c-2d2cd305c9b0#non-order-tables) * [Shop Performance](https://claude.ai/chat/8c3f96ff-b0d1-4cae-960c-2d2cd305c9b0#non-order-tables) * [Shop Product Performance](https://claude.ai/chat/8c3f96ff-b0d1-4cae-960c-2d2cd305c9b0#non-order-tables) #### Table Relationships * `orders` — keyed on shop + order ID * `order_payments` → `orders` — **joins on `__sync_key`, not an order\_id column** (it has none; one row per order) * `order_line_items.order_id` → `orders.id` * `order_line_item_combined_skus.order_id` → `orders.id`, `.order_line_item_id` → `order_line_items.id` * `order_price_detail.order_id` → `orders.id` (one row per order) * `order_line_item_price_detail.order_id` → `orders.id`, `.line_item_id` → `order_line_items.id` * `external_orders.order_id` → `orders.id` * `returns.order_id` → `orders.id` * `return_line_items.return_id` → `returns.return_id`, `.order_line_item_id` → `order_line_items.id` {% hint style="info" %} For multi-shop accounts, include `__shop_id` in any join made on raw IDs, since sync keys incorporate the shop. {% endhint %} #### Orders * Endpoint: `POST /order/202309/orders/search` * Update Method: UPSERT * Table Name: \[`tiktok_shop.orders`] | JSON Element | Database Column | | ---------------------------------------------------------- | ---------------------------------------- | | `id` | `id` | | `status` | `status` | | `fulfillment_type` | `fulfillment_type` | | `delivery_type` | `delivery_type` | | `create_time` | `create_time` | | `paid_time` | `paid_time` | | `update_time` | `update_time` | | `cancel_time` | `cancel_time` | | `cancel_reason` | `cancel_reason` | | `cancellation_initiator` | `cancellation_initiator` | | `payment_method_name` | `payment_method_name` | | `shipping_provider` | `shipping_provider` | | `shipping_provider_id` | `shipping_provider_id` | | `shipping_type` | `shipping_type` | | `tracking_number` | `tracking_number` | | `warehouse_id` | `warehouse_id` | | `buyer_message` | `buyer_message` | | `buyer_email` | `buyer_email` | | `buyer_nickname` | `buyer_nickname` | | `buyer_avatar` | `buyer_avatar` | | `user_id` | `user_id` | | `seller_note` | `seller_note` | | `is_cod` | `is_cod` | | `is_sample_order` | `is_sample_order` | | `is_on_hold_order` | `is_on_hold_order` | | `is_replacement_order` | `is_replacement_order` | | `replaced_order_id` | `replaced_order_id` | | `is_exchange_order` | `is_exchange_order` | | `exchange_source_order_id` | `exchange_source_order_id` | | `is_buyer_request_cancel` | `is_buyer_request_cancel` | | `request_cancel_time` | `request_cancel_time` | | `commerce_platform` | `commerce_platform` | | `order_type` | `order_type` | | `release_date` | `release_date` | | `cpf` | `cpf` | | `cpf_name` | `cpf_name` | | `consultation_id` | `consultation_id` | | `fast_delivery_program` | `fast_delivery_program` | | `fast_dispatch_sla_time` | `fast_dispatch_sla_time` | | `fulfillment_priority_level` | `fulfillment_priority_level` | | `auto_combine_group_id` | `auto_combine_group_id` | | `split_or_combine_tag` | `split_or_combine_tag` | | `need_upload_invoice` | `need_upload_invoice` | | `has_updated_recipient_address` | `has_updated_recipient_address` | | `rts_time` | `rts_time` | | `rts_sla_time` | `rts_sla_time` | | `tts_sla_time` | `tts_sla_time` | | `delivery_time` | `delivery_time` | | `delivery_sla_time` | `delivery_sla_time` | | `delivery_due_time` | `delivery_due_time` | | `delivery_option_id` | `delivery_option_id` | | `delivery_option_name` | `delivery_option_name` | | `delivery_option_required_delivery_time` | `delivery_option_required_delivery_time` | | `shipping_due_time` | `shipping_due_time` | | `collection_time` | `collection_time` | | `collection_due_time` | `collection_due_time` | | `cancel_order_sla_time` | `cancel_order_sla_time` | | `pick_up_cut_off_time` | `pick_up_cut_off_time` | | `recommended_shipping_time` | `recommended_shipping_time` | | `handling_duration.days` | `handling_duration_days` | | `handling_duration.type` | `handling_duration_type` | | `recipient_address.recipient_name` | `recipient_name` | | `recipient_address.first_name` | `recipient_first_name` | | `recipient_address.last_name` | `recipient_last_name` | | `recipient_address.first_name_local_script` | `recipient_first_name_local_script` | | `recipient_address.last_name_local_script` | `recipient_last_name_local_script` | | `recipient_address.recipient_full_address` | `recipient_full_address` | | `recipient_address.recipient_phone_number` | `recipient_phone_number` | | `recipient_address.address_detail` | `recipient_address_detail` | | `recipient_address.address_line1` | `recipient_address_line1` | | `recipient_address.address_line2` | `recipient_address_line2` | | `recipient_address.address_line3` | `recipient_address_line3` | | `recipient_address.address_line4` | `recipient_address_line4` | | `recipient_address.postal_code` | `recipient_postal_code` | | `recipient_address.region_code` | `recipient_region_code` | | `recipient_address.post_town` | `recipient_post_town` | | `recipient_address.district_info[0].address_level` | `recipient_district_address_level` | | `recipient_address.district_info[0].address_level_name` | `recipient_district_address_level_name` | | `recipient_address.district_info[0].address_name` | `recipient_district_address_name` | | `recipient_address.district_info[0].iso_code` | `recipient_district_iso_code` | | `recipient_address.delivery_preferences.drop_off_location` | `recipient_delivery_drop_off_location` | | `packages[].id` (comma-joined) | `package_ids` | | `order_rights[]` (comma-joined) | `order_rights` | | MD5(shop\_id + `id`) | `__sync_key` | #### Order Payments * Source: `payment` object in the Order List response * Update Method: UPSERT * Table Name: \[`tiktok_shop.order_payments`] One row per order. There is no `order_id` column — join to `orders` on `__sync_key`. | JSON Element | Database Column | | --------------------------------- | -------------------------------- | | `currency` | `currency` | | `sub_total` | `sub_total` | | `total_amount` | `total_amount` | | `original_total_product_price` | `original_total_product_price` | | `seller_discount` | `seller_discount` | | `platform_discount` | `platform_discount` | | `payment_platform_discount` | `payment_platform_discount` | | `payment_discount_service_fee` | `payment_discount_service_fee` | | `shipping_fee` | `shipping_fee` | | `original_shipping_fee` | `original_shipping_fee` | | `shipping_fee_seller_discount` | `shipping_fee_seller_discount` | | `shipping_fee_platform_discount` | `shipping_fee_platform_discount` | | `shipping_fee_cofunded_discount` | `shipping_fee_cofunded_discount` | | `shipping_fee_tax` | `shipping_fee_tax` | | `shipping_insurance_fee` | `shipping_insurance_fee` | | `tax` | `tax` | | `product_tax` | `product_tax` | | `retail_delivery_fee` | `retail_delivery_fee` | | `small_order_fee` | `small_order_fee` | | `buyer_service_fee` | `buyer_service_fee` | | `handling_fee` | `handling_fee` | | `item_insurance_fee` | `item_insurance_fee` | | `item_insurance_tax` | `item_insurance_tax` | | `distance_shipping_fee` | `distance_shipping_fee` | | `distance_fee` | `distance_fee` | | MD5(shop\_id + parent order `id`) | `__sync_key` | #### Order Line Items * Source: `line_items[]` in the Order List response * Update Method: UPSERT * Table Name: \[`tiktok_shop.order_line_items`] | JSON Element | Database Column | | ------------------------ | ------------------------ | | parent `orders[].id` | `order_id` | | `id` | `id` | | `product_id` | `product_id` | | `product_name` | `product_name` | | `sku_id` | `sku_id` | | `sku_name` | `sku_name` | | `seller_sku` | `seller_sku` | | `sku_type` | `sku_type` | | `sku_image` | `sku_image` | | `sale_price` | `sale_price` | | `original_price` | `original_price` | | `platform_discount` | `platform_discount` | | `seller_discount` | `seller_discount` | | `currency` | `currency` | | `pfand_fee` | `pfand_fee` | | `retail_delivery_fee` | `retail_delivery_fee` | | `buyer_service_fee` | `buyer_service_fee` | | `small_order_fee` | `small_order_fee` | | `distance_shipping_fee` | `distance_shipping_fee` | | `distance_fee` | `distance_fee` | | `display_status` | `display_status` | | `package_status` | `package_status` | | `package_id` | `package_id` | | `cancel_reason` | `cancel_reason` | | `cancel_user` | `cancel_user` | | `rts_time` | `rts_time` | | `tracking_number` | `tracking_number` | | `shipping_provider_name` | `shipping_provider_name` | | `shipping_provider_id` | `shipping_provider_id` | | `is_gift` | `is_gift` | | `is_dangerous_good` | `is_dangerous_good` | | `needs_prescription` | `needs_prescription` | | `gift_retail_price` | `gift_retail_price` | | `is_unboxing_item` | `is_unboxing_item` | | `unboxing_sku_code` | `unboxing_sku_code` | | `handling_duration_days` | `handling_duration_days` | | MD5(shop\_id + `id`) | `__sync_key` | #### Order Line Item Combined SKUs * Source: `line_items[].combined_listing_skus[]` in the Order List response * Update Method: UPSERT * Table Name: \[`tiktok_shop.order_line_item_combined_skus`] | JSON Element | Database Column | | ----------------------------------------- | -------------------- | | parent `orders[].id` | `order_id` | | parent `line_items[].id` | `order_line_item_id` | | `sku_id` | `sku_id` | | `sku_count` | `sku_count` | | `product_id` | `product_id` | | `seller_sku` | `seller_sku` | | MD5(shop\_id + line item `id` + `sku_id`) | `__sync_key` | #### Order Price Detail * Endpoint: `GET /order/202407/orders/{order_id}/price_detail` * Update Method: UPSERT * Table Name: \[`tiktok_shop.order_price_detail`] One row per order. | JSON Element | Database Column | | ----------------------------------------- | ----------------------------------------- | | order id (from job context) | `order_id` | | `currency` | `currency` | | `total` | `total` | | `payment` | `payment` | | `subtotal` | `subtotal` | | `sku_list_price` | `sku_list_price` | | `sku_sale_price` | `sku_sale_price` | | `subtotal_deduction_seller` | `subtotal_deduction_seller` | | `subtotal_deduction_platform` | `subtotal_deduction_platform` | | `subtotal_tax_amount` | `subtotal_tax_amount` | | `voucher_deduction_seller` | `voucher_deduction_seller` | | `voucher_deduction_platform` | `voucher_deduction_platform` | | `shipping_list_price` | `shipping_list_price` | | `shipping_sale_price` | `shipping_sale_price` | | `shipping_fee_deduction_seller` | `shipping_fee_deduction_seller` | | `shipping_fee_deduction_platform` | `shipping_fee_deduction_platform` | | `shipping_fee_deduction_platform_voucher` | `shipping_fee_deduction_platform_voucher` | | `tax_amount` | `tax_amount` | | `tax_rate` | `tax_rate` | | `net_price_amount` | `net_price_amount` | | `cod_fee` | `cod_fee` | | `cod_fee_net_amount` | `cod_fee_net_amount` | | `sku_gift_original_price` | `sku_gift_original_price` | | `sku_gift_net_price` | `sku_gift_net_price` | | `distance_shipping_fee` | `distance_shipping_fee` | | `distance_fee` | `distance_fee` | | MD5(shop\_id + order\_id) | `__sync_key` | #### Order Line Item Price Detail * Source: `line_items[]` in the Price Detail response * Update Method: UPSERT * Table Name: \[`tiktok_shop.order_line_item_price_detail`] Contains the same columns as `order_price_detail`, with the addition of `line_item_id` (← `id`) and `cod_fee_amount` (← `cod_fee_amount`) in place of `cod_fee_net_amount`. | JSON Element | Database Column | | ------------------------------------------ | ----------------------------------------- | | order id (from job context) | `order_id` | | `id` | `line_item_id` | | `currency` | `currency` | | `total` | `total` | | `payment` | `payment` | | `subtotal` | `subtotal` | | `sku_list_price` | `sku_list_price` | | `sku_sale_price` | `sku_sale_price` | | `subtotal_deduction_seller` | `subtotal_deduction_seller` | | `subtotal_deduction_platform` | `subtotal_deduction_platform` | | `subtotal_tax_amount` | `subtotal_tax_amount` | | `voucher_deduction_seller` | `voucher_deduction_seller` | | `voucher_deduction_platform` | `voucher_deduction_platform` | | `shipping_list_price` | `shipping_list_price` | | `shipping_sale_price` | `shipping_sale_price` | | `shipping_fee_deduction_seller` | `shipping_fee_deduction_seller` | | `shipping_fee_deduction_platform` | `shipping_fee_deduction_platform` | | `shipping_fee_deduction_platform_voucher` | `shipping_fee_deduction_platform_voucher` | | `tax_amount` | `tax_amount` | | `tax_rate` | `tax_rate` | | `net_price_amount` | `net_price_amount` | | `cod_fee` | `cod_fee` | | `cod_fee_amount` | `cod_fee_amount` | | `sku_gift_original_price` | `sku_gift_original_price` | | `sku_gift_net_price` | `sku_gift_net_price` | | `distance_shipping_fee` | `distance_shipping_fee` | | `distance_fee` | `distance_fee` | | MD5(shop\_id + order\_id + line item `id`) | `__sync_key` | #### External Orders * Endpoint: `GET /order/202406/orders/{order_id}/external_orders` * Update Method: UPSERT * Table Name: \[`tiktok_shop.external_orders`] Retrieved once per order per configured external platform. | JSON Element | Database Column | | ----------------------------------- | --------------- | | order id (from job context) | `order_id` | | `id` (external platform's order id) | `id` | | `platform` | `platform` | | MD5(shop\_id + order\_id + `id`) | `__sync_key` | #### Returns * Endpoint: `POST /return_refund/202309/returns/search` * Update Method: UPSERT * Table Name: \[`tiktok_shop.returns`] | JSON Element | Database Column | | --------------------------------------- | ------------------------------- | | `order_id` | `order_id` | | `return_id` | `return_id` | | `return_type` | `return_type` | | `return_status` | `return_status` | | `arbitration_status` | `arbitration_status` | | `role` | `role` | | `return_reason` | `return_reason` | | `return_reason_text` | `return_reason_text` | | `shipment_type` | `shipment_type` | | `handover_method` | `handover_method` | | `return_tracking_number` | `return_tracking_number` | | `return_provider_name` | `return_provider_name` | | `return_provider_id` | `return_provider_id` | | `return_method` | `return_method` | | `return_shipping_document_type` | `return_shipping_document_type` | | `pre_return_id` | `pre_return_id` | | `next_return_id` | `next_return_id` | | `is_combined_return` | `is_combined_return` | | `combined_return_id` | `combined_return_id` | | `can_buyer_keep_item` | `can_buyer_keep_item` | | `seller_proposed_return_type` | `seller_proposed_return_type` | | `buyer_rejected_partial_refund` | `buyer_rejected_partial_refund` | | `is_quick_refund` | `is_quick_refund` | | `create_time` | `create_time` | | `update_time` | `update_time` | | `partial_refund.currency` | `partial_refund_currency` | | `partial_refund.amount` | `partial_refund_amount` | | `return_warehouse_address.full_address` | `return_warehouse_full_address` | | MD5(shop\_id + `return_id`) | `__sync_key` | #### Return Line Items * Source: `return_line_items[]` in the Returns response * Update Method: UPSERT * Table Name: \[`tiktok_shop.return_line_items`] | JSON Element | Database Column | | -------------------------------------------------- | ------------------------------------------ | | parent `return_orders[].return_id` | `return_id` | | `return_line_item_id` | `return_line_item_id` | | `order_line_item_id` | `order_line_item_id` | | `sku_id` | `sku_id` | | `sku_name` | `sku_name` | | `product_name` | `product_name` | | `seller_sku` | `seller_sku` | | `product_image.url` | `product_image_url` | | `product_image.width` | `product_image_width` | | `product_image.height` | `product_image_height` | | `refund_amount.currency` | `refund_amount_currency` | | `refund_amount.refund_total` | `refund_amount_refund_total` | | `refund_amount.refund_subtotal` | `refund_amount_refund_subtotal` | | `refund_amount.refund_shipping_fee` | `refund_amount_refund_refund_shipping_fee` | | `refund_amount.refund_tax` | `refund_amount_refund_tax` | | `refund_amount.retail_delivery_fee` | `refund_amount_retail_delivery_fee` | | `refund_amount.buyer_service_fee` | `refund_amount_buyer_service_fee` | | MD5(shop\_id + return\_id + `return_line_item_id`) | `__sync_key` | #### Non-order tables In addition to the order tables above, the extractor creates the following tables for products, promotions, and shop analytics: | Table | Endpoint | Description | | --------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------- | | `tiktok_shop.products` | `POST /product/202502/products/search` | Product catalog | | `tiktok_shop.product_skus` | `POST /product/202502/products/search` | SKU-level product data | | `tiktok_shop.product_sku_inventory` | `POST /product/202502/products/search` | SKU inventory | | `tiktok_shop.product_sku_fees` | `POST /product/202502/products/search` | SKU-level fees | | `tiktok_shop.product_family_products` | `POST /product/202502/products/search` | Product family relationships | | `tiktok_shop.coupons` | `POST /promotion/202406/coupons/search` | Coupon records | | `tiktok_shop.activities` | `POST /promotion/202309/activities/search` | Promotional activity records | | `tiktok_shop.activity_bmsm_discount_details` | `POST /promotion/202309/activities/search` | "Buy more, save more" discount detail | | `tiktok_shop.shop_performance` | `GET /analytics/202509/shop/performance` | Shop-level performance analytics | | `tiktok_shop.shop_performance_gmv_breakdowns` | `GET /analytics/202509/shop/performance` | Shop performance broken down by GMV | | `tiktok_shop.shop_performance_gross_revenue_breakdowns` | `GET /analytics/202509/shop/performance` | Shop performance broken down by gross revenue | | `tiktok_shop.shop_product_performance` | `GET /analytics/202509/shop_products/{product_id}/performance` | Product-level performance analytics | | `tiktok_shop.shop_product_performance_sales_breakdowns` | `GET /analytics/202509/shop_products/{product_id}/performance` | Product performance broken down by sales | | `tiktok_shop.shop_product_performance_traffic_breakdowns` | `GET /analytics/202509/shop_products/{product_id}/performance` | Product performance broken down by traffic |