TikTok Shop
Get Config
Returns the public OAuth config (app_key, redirect_url) for the requested environment. the application UI uses this to build the TikTok authorization URL.
OAuth Init
Generates a state UUID, caches it for 15 minutes, and returns the TikTok authorization URL the user should be redirected to. Optionally accepts an integration_instance_id to re-link an existing instance.
List Integration Instances
List Integration Instances
Show Integration Instance
Returns a single integration instance with integration and salesChannel relations.
Update Integration Instance
Patch-update name and/or integration_settings. integration_settings is deep-merged into the existing JSON.
Delete Integration Instance
Deletes the integration instance. Webhook unsubscribe is best-effort — local delete proceeds even on remote failure.
Get Dashboard Metrics
Aggregate dashboard metrics for one or many TikTok Shop connections: the connection summaries, synced entity counts (orders, products, returns, refunds, transactions, shops), a financial summary (gross/net revenue, refunds, units sold) for an optional period, and per-entity sync health.
Get Shop Info
Get the TikTok Shop metadata for a connection: shop name, id, cipher, region, seller id, and the authorizing seller's account details captured during authorization.
List Access Scopes
List the TikTok Shop API permission scopes granted to this connection during authorization, each with a human-readable description. Use this to verify the connection has the permissions a feature needs (orders, products, fulfillment, logistics, finance, returns, webhooks).
List Orders
Spatie QueryBuilder paginated list of TikTok Shop orders across instances. Allowed filters: integration_instance_ids, status (TikTok Shop single-axis enum: UNPAID|ON_HOLD|AWAITING_SHIPMENT|PARTIALLY_SHIPPING|AWAITING_COLLECTION|IN_TRANSIT|DELIVERED|COMPLETED|CANCELLED), fulfillment_method, currency, payment_method_name, cancelled, archived, status_state (active|archived|all), search (matches tiktok_order_id/buyer_email/recipient_name), date_from, date_to. Allowed sorts: id, tiktok_order_id, status, total_amount, tiktok_create_time, tiktok_update_time, tiktok_paid_time, last_sync_at, created_at, updated_at. Default sort: -tiktok_create_time. per_page defaults to 10.
Show Order
Returns a single TikTok Shop order with lineItems and packages eager-loaded.
Get Raw Order from TikTok
Fetches the live order JSON directly from the TikTok Shop API (`/order/202309/orders?ids=...`) for a single previously-synced order. Mirrors the Shopify `getRawOrderFromShopify` pattern — used by the frontend Raw Data section as a fetch-on-demand tool to inspect the current upstream payload without writing it to the database.
Refresh Orders from TikTok
Dispatches a tracked job to pull recent orders from TikTok Shop.
Refresh Single Order
Re-syncs a single order by TikTok order ID.
Search Orders (Local DB)
Searches LOCAL DB for already-synced TikTok Shop orders. Unlike Shopify's equivalent endpoint, this does NOT hit the TikTok Shop API — TikTok's API does not currently support free-text order search. Use this to find orders already synced into SKU.io and re-trigger an update via Refresh Single Order.
Submit Tracking
Dispatches a background job to push tracking numbers up to TikTok for the order's packages. Returns a tracked_job_log_id.
List Shipping Providers
Returns the list of TikTok-recognized shipping providers for the instance (used to populate dropdowns in the shipping method mapping UI).
Get Latest Sync Info
Returns sync metadata: latest_order_name, latest_order_date, sync_cursor_at, total_orders, last_sync_at.
Archive Order
Soft-archives a TikTok Shop order. Sets archived_at timestamp.
Unarchive Order
Restores a previously archived TikTok Shop order. Clears archived_at.
Bulk Archive Orders
Bulk-archives orders. Either pass an explicit `ids` array, or `apply_to_all: true` with the current `filters` object to archive every matching order. Returns archived_count.
Bulk Unarchive Orders
Bulk-unarchives orders. Either pass an explicit `ids` array, or `apply_to_all: true` with the current `filters` object. Returns unarchived_count.
Delete Order
Permanently deletes a TikTok Shop order from SKU.io (does not affect TikTok).
Bulk Delete Orders
Bulk-deletes orders. Either pass an explicit `ids` array, or `apply_to_all: true` with the current `filters` object. Returns deleted_count.
Create SKU Orders from TikTok Shop
Create SKU sales orders from TikTok Shop orders. Mirrors the Shopify endpoint. Supports three request shapes:
Update SKU Orders from TikTok Shop
Update existing SKU sales orders from their linked TikTok Shop orders. Re-derives the SalesOrder DTO and persists changes. Only TikTok Shop orders that already have a linked SalesOrder are eligible. Pass either `ids: [...]` for a specific subset, or `update_all_orders: true` (optionally with `filters: {...}`). The `use_jobs` flag is accepted for parity with Shopify but is currently ignored — TikTok always runs synchronously.
Delete Linked SKU Order
Delete the SKU sales order linked to a single TikTok Shop order. The TikTok Shop order itself is kept intact. Pass `archive_tiktok_shop_order=true` to additionally archive the TikTok Shop order so it won't be re-created on the next sync. Returns 404 if no SKU order is linked.
Bulk Delete Linked SKU Orders
Bulk-delete the SKU sales orders linked to the given TikTok Shop orders. The TikTok Shop orders themselves are kept intact unless `archive_tiktok_shop_orders=true` is passed. Pass either an explicit `ids` array, or `apply_to_all: true` with the current `filters` object. Returns the deleted count. TODO: For large batches a tracked job should be dispatched (currently runs synchronously, mirroring Shopify's a background job).
Query Pre-Start-Date Orders
Query TikTok Shop for orders predating the inventory start date in a given window.
Search Pre-Start-Date Orders
Search TikTok Shop for a specific pre-start-date order by ID or buyer email.
Import Pre-Start-Date Orders
Import selected pre-start-date orders from TikTok Shop by their TikTok order ids. Each order is fetched from the TikTok Shop API and stored, flagged as a pre-start-date import.
List Products
List Products
List Product SKUs (Flattened Mapping List)
Flattened one-row-per-SKU product list — the Shopify-parity product-mapping table. Unlike **List Products** (one row per TikTok product), each row here is a single `TikTokShopProductSku` variant carrying its own mapping block (`product`, `sku_product`, `subscription_offering`, `mapped_at`, `mapped_sku`), so the shared frontend mapped-product column renders 1:1 exactly as it does for Shopify variants.
Show Product
Returns a single TikTok Shop product with skus and shop eager-loaded.
Sync Products (Tracked)
Dispatches a background job to fetch all products for the instance. Returns a tracked_job_log_id.
Smart Match SKU to SKU.io Products
Suggest SKU.io Products to map a TikTok Shop SKU (TikTokShopProductSku) to, before the user maps it. Mirrors Shopify's smart-match, but operates at TikTok's per-SKU listing grain (Shopify matches per-variant).
Create SKU.io Product from SKU
Create a brand-new SKU.io Product from a TikTok Shop SKU's own data (SKU, name, price) and map the SKU to it in one step. Mirrors Shopify's create-sku-product, but operates at TikTok's per-SKU listing grain (Shopify creates per-variant).
Map Product SKU
Map a TikTok Shop product SKU (TikTokShopProductSku) to a SKU.io Product or Subscription Offering. Mirrors Shopify single-map. Body requires `sku_id` plus exactly one of `product_id` or `subscription_offering_id`. Response includes the reloaded product with skus + product listing.
Unmap Product SKU
Unmap a TikTok Shop product SKU. Deletes the underlying ProductListing. Returns 422 if the SKU is not currently mapped.
Archive Product
Soft-archive a single TikTok Shop product (sets archived_at). Mirrors Shopify single-archive.
Unarchive Product
Restore an archived TikTok Shop product (clears archived_at). Mirrors Shopify single-unarchive.
Delete Product
Hard-delete a single TikTok Shop product and its child SKUs. Mirrors Shopify single delete.
Bulk Archive Products
Bulk-archives TikTok Shop products (sets archived_at). Either pass an explicit `ids` array, or `apply_to_all: true` with the current `filters` object to archive every product matching the listing filters. Returns archived_count.
Bulk Unarchive Products
Bulk-unarchives TikTok Shop products (clears archived_at). Either pass an explicit `ids` array, or `apply_to_all: true` with the current `filters` object. Returns unarchived_count.
Bulk Delete Products
Hard-deletes TikTok Shop products (and their child SKUs) in bulk. Either pass an explicit `ids` array, or `apply_to_all: true` with the current `filters` object. Returns deleted_count.
Bulk Unmap Product SKUs
Bulk-unmaps TikTok Shop product SKUs from their SKU.io ProductListings (deletes the ProductListing records). Per-SKU, not per-product, because mapping is at the SKU level.
Download CSV Mappings
Download a CSV of TikTok Shop SKU → SKU.io product mappings, scoped by selection, unmapped-only, or all (filtered).
Upload CSV Mappings
Upload an edited CSV (downloaded from the Download CSV Mappings endpoint) to bulk-apply TikTok SKU → SKU.io product mappings in one pass. Validates and applies row-by-row.
Validate CSV Mappings
Parse/preview half of the two-step CSV import — mirrors Shopify's Validate Bulk Mapping CSV, but operates per-SKU (TikTok lists each SKU as its own variant, keyed on `tiktok_sku_id`).
Apply CSV Mappings
Commit half of the two-step CSV import — mirrors Shopify's Apply Bulk Mapping CSV. Applies the `{tiktok_shop_product_sku_id, sku_product_id}` pairings returned by the Validate CSV Mappings endpoint. Each pairing maps a flattened TikTok SKU to a SKU.io product via the canonical mapping path (creates/updates the ProductListing and re-links any unmapped sales-order lines).
Get Raw Product from TikTok
Fetches the live raw product JSON directly from the TikTok Shop API (`GET /product/202309/products/{tiktok_product_id}`) for the given local product. Used by the product detail page's 'Raw Data from TikTok' accordion when the user clicks 'Load Raw Data from TikTok'.
Get Orders Containing Product
Returns a paginated list of TikTok Shop orders that contain this product (orders whose line items reference the product's `tiktok_product_id`). Used by the product detail page's 'Orders Containing This Product' accordion.
Bulk Map / Unmap / Create / Remap Product SKUs (Sync)
Synchronous per-SKU bulk mapping engine backing the frontend BulkMappingModal for below-threshold selections. Runs each resolved TikTok Shop SKU through the mapping manager and returns Shopify-parity count keys.
Bulk Map Product SKUs (Tracked)
Queued counterpart to `products/bulk`, dispatched when the BulkMappingModal crosses its tracked-operation threshold. Same body contract as `products/bulk` (`action` = `map` | `unmap` | `create` | `remap`, plus `selection` and `options`). Dispatches a tracked job and returns its `tracked_job_log_id` for polling via `products/bulk-progress/{id}`.
Get Bulk Mapping Progress
Fetch progress for a tracked bulk mapping operation started by `products/bulk-tracked`. Returns the tracked job log object for the given `trackedJobLogId` — the same shape the tracked job log endpoints consumes (status, processed/total items, progress percentage, messages, results).
Map to Existing SKUs (Bulk, Queued)
Queue a bulk 'map to existing SKU.io products only' operation (no product creation) over the shared toolbar selection contract. Guarded by the instance's configured field mappings.
Create Products from Mappings (Bulk, Queued)
Queue a bulk 'create new SKU.io products from unmapped SKUs' operation over the shared toolbar selection contract. Guarded by the instance's configured field mappings. Same body and response shape as `map-to-existing-skus`, but the queued job creates a SKU.io product from each unmapped SKU's channel attributes (linking an existing product when one already has the matching SKU) and maps it.
Get Latest Sync Info
Summary of the product catalog sync for a connection: the most recently updated product (by TikTok's update time), the total number of synced products, and when the last product sync ran.
List Locations
Returns all known TikTok Shop warehouses for the integration instance (from the local cache).
Refresh Locations from TikTok
Pull the seller's warehouses from TikTok Shop into the local cache and seed the per-warehouse master-of-stock panel. Returns the number of warehouses synced.
List Inventory Comparison
Paginated inventory comparison for this connection — one row per SKU × TikTok warehouse. Each row pairs the SKU.io computed available quantity (`sku_quantity`) with the last-observed TikTok quantity (`sales_channel_quantity`) and derives a `status`:
Get Inventory Summary
KPI counts for the inventory page: total cache rows, in-sync count, variance count, and needs-recalculation count, the not-managed count (warehouses where SKU.io is not the master of stock — inventory is not synced for them), plus the most recent fetch (`last_fetch_at`) and push (`last_sync_at`) timestamps across this connection's rows. Requires a Bearer token.
Recache Inventory
Recompute the per-warehouse available-quantity cache for every mapped listing on this connection, applying the configured master-of-stock, buffer-stock, and min/max rules. Runs asynchronously and returns a tracked-job id you can poll via Get Recache Progress. Requires a Bearer token.
Get Recache Progress
Poll the tracked-job log for a recache job (see Recache Inventory). Returns the TrackedJobLog resource with status, progress, and completion results. Requires a Bearer token.
Sync Inventory to TikTok Shop
Push the cached available quantities to TikTok Shop for every listing whose SKU.io quantity differs from what TikTok currently holds. Runs asynchronously and returns a tracked-job id you can poll via Get Sync Progress. Typically run after Recache Inventory. Requires a Bearer token.
Get Sync Progress
Poll the tracked-job log for a sync job (see Sync Inventory to TikTok Shop). Returns the TrackedJobLog resource with status, progress, and completion results. Requires a Bearer token.
Fetch Live Inventory
Fetch live per-warehouse quantities from TikTok Shop into the sales-channel cache. TikTok has no bulk inventory-read endpoint, so this issues per-product detail GETs for every product with at least one mapped SKU. This is an inbound observation only — it writes `sales_channel_quantity` / `sales_channel_quantity_updated_at` and never the push timestamp. Runs asynchronously and returns a tracked-job id you can poll via Get Fetch Live Progress. Requires a Bearer token.
Get Fetch Live Progress
Poll the tracked-job log for a fetch-live job (see Fetch Live Inventory). Returns the TrackedJobLog resource with status, per-product progress, and completion results. Requires a Bearer token.
List Packages
Paginated list of TikTok Shop packages across one or many integration instances. Includes related order summary.
List Pending Fulfillments
Paginated list of SalesOrderFulfillment records awaiting TikTok tracking submission for the given integration instance.
Fulfillment Sync Stats
Counts and sync-schedule note for the fulfillments page.
Submit Single Fulfillment
Submit one SalesOrderFulfillment's tracking to TikTok Shop.
Submit Bulk Fulfillments
Submit tracking for a list of SalesOrderFulfillment IDs.
Submit All Pending Fulfillments
Submit tracking for every pending fulfillment for this integration instance.
List Returns
List Returns
Show Return
Returns a single TikTok Shop return with the related order eager-loaded.
Sync Returns (Tracked)
Dispatches a background job for the instance. Returns a tracked_job_log_id.
List Refunds
List Refunds
Show Refund
Returns a single TikTok Shop refund with the related order eager-loaded.
Sync Refunds (Tracked)
Dispatches a background job for the instance. Returns a tracked_job_log_id.
List Transactions
Paginated list of TikTok Shop transactions (statement transactions) across integration instances. Supports Spatie QueryBuilder filters and sorts.
Get Transaction
Returns a single TikTok Shop transaction with its `integration_instance` and (when matched by `related_order_id` -> `tiktok_order_id`) `order` relations eager-loaded for the detail page. Includes native columns for money breakdown (revenue_amount, fee_amount, tax_amount, net_amount, settlement_amount, shipping_cost_amount, reserve_amount), identifiers (adjustment_id, associated_order_id), `statement_time`, and JSON sub-structures `fee_breakdown_json` / `tax_breakdown_json`.
Get Raw Transaction from TikTok
Fetches the live transaction JSON directly from the TikTok Shop Finance API for a single previously-synced transaction. It reads the parent statement's transactions via `GET /finance/202309/statements/{statement_id}/statement_transactions` (paginated via `page_token`, `sort_field=order_create_time`) and returns the entry whose id matches the stored `tiktok_transaction_id`. Mirrors the `Get Raw Order from TikTok` pattern — used by the frontend Raw Data section as a fetch-on-demand tool to inspect the current upstream payload without writing it to the database.
Sync Transactions (Tracked)
Dispatches a background job. Returns a tracked_job_log_id.
List Warehouse Mappings
Returns the existing warehouse mappings, the mappable TikTok Shop warehouses for the instance, and all SKU.io warehouses.
Upsert Warehouse Mapping
Create or update a warehouse mapping for the instance.
Delete Warehouse Mapping
Deletes the mapping for the given TikTok Shop warehouse id.
List Shipping Method Mappings
Returns existing mappings, the TikTok shipping provider list (best-effort), and all SKU.io shipping methods.
Upsert Shipping Method Mapping
Create or update a mapping between a SKU.io shipping method and a TikTok shipping provider.
Delete Shipping Method Mapping
Deletes the mapping for the given SKU.io shipping method id.
List Payment Method Mappings
Returns existing mappings, distinct observed TikTok payment method names (from synced orders), and all SKU.io PaymentType records.
Upsert Payment Method Mapping
Create or update a mapping between a TikTok payment method name and a SKU.io PaymentType.
Delete Payment Method Mapping
Deletes the mapping for a given TikTok payment method name.
Get Available Fields
Returns the catalog of available TikTok Shop source fields (grouped by Identifiers / Product Info / Variant Details / Pricing / Media / Timestamps) and SKU.io target fields (including dynamic ProductPricingTier / SupplierPricingTier / Attribute fields). Use this to populate field selectors before configuring mappings.
Get Field Mappings
Returns the full mapping picture for a TikTok Shop integration instance: available source/target fields, system defaults, custom (overridden) mappings persisted by the merchant, and the effective merged set used during product creation. Each mapping entry contains `listing_field` (TikTok side), `sku_field` (SKU.io side), and an optional `parsers` array of transforms (rules: `fr` find/replace, `tl` trim-left, `tr` trim-right, `append`).
Update Field Mappings
Replace the custom field mappings for this integration instance. Body: `mappings` (array, required) — each entry has `listing_field` (string, required), `sku_field` (string, required), and `parsers` (array, optional; each parser has `rule` one of `fr`/`tl`/`tr`/`append` and `args` shape depending on rule). The submitted set fully replaces any existing custom mappings; system defaults remain in effect for fields not included. Returns the refreshed effective mappings.
List Webhook Events
Paginated list of TikTok Shop webhook events across one or many integration instances.
Delete All Webhook Events
Permanently delete ALL webhook events, optionally scoped to one or more integration instances. Cannot be undone.
Get Webhook Event Stats
Counts of webhook events grouped by processing status (pending, processing, completed, failed) plus a total. Used to power the summary cards on the Webhooks Events tab.
Show Webhook Event
Show a single webhook event including its raw payload.
Delete Webhook Event
Permanently delete a single webhook event.
Process Webhook Event
Re-dispatch the processing job for a webhook event without resetting its status.
Reprocess Webhook Event
Reset a webhook event back to pending (clears processed_at and processing_error) and re-dispatch the processing job. Use this for failed events.
Bulk Delete Webhook Events
Permanently delete multiple webhook events by ID.
Bulk Process Pending Webhook Events
Loop pending webhook events and dispatch a background job for each. Optionally scope to specific integration instances and cap the batch with `limit` (max 500, default 100).
Bulk Retry Failed Webhook Events
Reset failed webhook events to pending and re-dispatch a background job for each. Optionally scope to integration instances and cap with `limit` (max 500, default 100).
Receive Webhook (TikTok → SKU.io)
Global (per-environment) endpoint that receives signed webhook events from TikTok Shop — this is the URL configured on the TikTok Shop app.
OAuth Callback
Browser redirect target after the merchant authorizes the app on TikTok. Exchanges the auth code for access/refresh tokens, persists a TikTokShopIntegrationInstance, syncs authorized shops, subscribes webhooks, dispatches the initial product + recent-order backfill on the interactive queue (a background job + a background job), and redirects into the SPA. NOT a JSON endpoint.