SPS API Merchant Performance Diagnosis: ISV Integration Use Cases

An ISV-developed App can use five read-only SPS APIs to build an end-to-end journey: overview, prioritization, diagnosis, object-level drill-down, action, and review. The App frontend first displays the merchant’s SPS, dimensions, peer ranking, and benefits; then prioritizes Top Opportunity metrics for diagnosis, identifies affected products, orders, logistics providers, or conversations, and converts recommendations into executable tasks. The SPS API does not modify products, orders, or customer service settings. Actions must either deep-link to TikTok Shop Seller Center or be handled by the App’s own capabilities.

1. View the SPS overview and benefit gaps;

This solution covers six user cases:

1. Identify priority improvement metrics and complete metric diagnosis;
2. Reduce product-satisfaction issues (NRR/NBFR);
3. Stabilize fulfillment and logistics performance (SFCR/OTDR);
4. Improve customer service and aftersales efficiency (IM_DSAT/AHT);
5. Build an action plan, monitor by cycle, and review results continuously.

Implementation must treat API-returned status, benefits.is_unlocked, benchmarks, top_reason_text, and update_time as the source of truth. Do not hard-code tier thresholds or benefit requirements in the client. Displayed scores are rounded, and some benefits have additional eligibility requirements; do not predict benefit unlocks using sps_score >= unlock_score.

Target Users and Systems

Terminology: In this document, App means an ISV-developed application used by merchants; App frontend means the pages merchants interact with directly; and App backend (BFF) means the backend service that calls the SPS API for the App frontend, handles authentication, and normalizes data.

In Scope

Included:

• Overall SPS score, tier, peer ranking, primary category, dimension scores, and benefits;
• Status, score, value, benchmarks, trend, calculation details, and diagnosis conclusions for all six metrics;
• Drill-down by product, order, logistics provider, aftersales type, and conversation;
• Recommended Actions, Seller Center deep links, and App-owned action plans;
• NIL, no data, partial data, pagination, and expired authorization.

Excluded:

• Modifying products, inventory, logistics, or customer service settings through the SPS API;
• Submitting an appeal through the SPS API;
• Calculating or predicting the official SPS within the App;
• Production rollout outside the United States. The five endpoints currently specified support US shops only.

SPS Rules at a Glance

• SPS is a dynamic score from 0 to 5. Merchants generally become eligible after receiving at least 30 delivered orders in the previous 90 days. Risk-controlled orders, sample orders, gift orders, and certain other orders may be excluded.
• SPS uses the highest-selling category from the previous 90 days as the primary category and evaluates the shop against benchmarks for peer merchants in that category.
• Recent orders carry more weight. Current official guidance states that the weight decays by 0.7 every 15 days.
• Scope of NIL: Once a shop has received an overall SPS, the overall score is normally not NIL. However, each of the six SPS metrics is evaluated independently. If a metric does not meet its scoring eligibility conditions, it may return status=NIL with no valid score even while the overall SPS and other metrics are available. The App must continue to show the overall SPS and other scored metrics, render only the affected metric as “Insufficient data,” and must not treat it as 0 or turn the entire SPS page into an empty state. The platform redistributes that metric’s weight across other scored metrics according to its rules.
• Merchants should prioritize metrics marked Top Opportunity, but the App must not derive that label independently.
• Low-volume protection, excluded orders, and score adjustments are calculated by the platform. The App should explain the returned results rather than recreate the scoring algorithm.

Six Metrics and Data Capabilities

Display the API value of evaluate_duration_days as the source of truth for the evaluation period. The table above is only a reference for the current official rules.

System Architecture

Image

Page-Level Calling Strategy

Image

API-Calling Principles

1. Fetch Overview first, then fetch Metrics based on the result. When Overview returns a valid overall SPS, load Metrics. If an individual metrics[].status=NIL, keep the overall SPS and other scored metrics visible, and show “Insufficient data” only for that metric; diagnosis and drill-down availability must follow the corresponding API response. Show an overview-level empty state only when the shop has not yet met overall SPS eligibility or Overview is unavailable. Lazy-load Diagnosis, Top Items, and Problem Details when the merchant opens them.
2. Use update_time to indicate data freshness. Show “Data updated at…” on the page. If update_time remains unchanged after a refresh, do not imply that the score has been recalculated.
3. Interpret results using API status fields. Prefer status and status_text; do not reclassify a metric solely by comparing value with thresholds.
4. Route by endpoint capability.top_items does not support SFCR or IM_DSAT; use problem_details directly for these two metrics.
5. Pass locale through for internationalization. Include locale in requests and prioritize localized names and descriptions returned by the API. Use only metric_code, status, and sps_tier as business-logic keys—not localized labels.
6. Handle unknown metrics gracefully. This document lists six metrics, while field descriptions use “possible values include.” Unknown metric_code values must be displayed safely or ignored without causing the page to fail.

Scenario Overview

The store owner wants to view SPS directly in the App frontend used for daily operations, without switching to Seller Center. They need to quickly understand the store’s current performance, the dimension that most needs improvement, its position relative to peer sellers, and which business benefits are unlocked or close to being unlocked. Trigger conditions: The merchant has completed authorization and the store is a US shop. Primary role: Store owner. Successful outcome: The merchant confirms the current SPS status within 30 seconds and opens the highest-priority issue for diagnosis.

Merchant Flow

The diagram below presents the complete merchant journey as “flow step — purpose and key interaction — App UI demo.” If the shop has an overall SPS but an individual metrics[].status=NIL, the App frontend must keep the SPS Overview, other scored metrics, and benefit information visible, and show “Insufficient data” with the current evaluation period only on the affected metric card. It must not turn the entire page into an empty state.

Image

API Call Flow

Image

Page-to-Field Mapping

Optimization Opportunities and Actions

UI Interaction Requirements

• The initial screen should highlight SPS, Top Opportunity, the three dimensions, and the data update time, with the label “Latest calculated result; not real-time monitoring.”
• Group benefits into unlocked and pending-unlock sections, without using fear-based copy.
• When metrics[].status=NIL, use the “Insufficient data” state only for that metric. Keep the overall SPS, other metrics, and benefits visible, and do not display a red score of 0.
• After the merchant selects a Top Issue, preserve the source context and restore the previous scroll position when they return to Overview.

Scenario Overview

The operations team knows the SPS score is low but cannot determine which metric to improve first or how far the current value is from the peer benchmark. The App frontend combines data from the Metrics and Diagnosis APIs on one page to explain what the problem is, why it occurred, how far the store is from the target, and whether the trend is improving. Primary roles: Store owner and domain operations leads. Successful outcome: The merchant selects a clearly defined priority metric and either drills down to affected records or creates an Action.

Merchant Flow

The diagram below includes the corresponding App UI demo under each diagnostic step. At the final step, the merchant can either drill down to affected records or add the recommendation directly to the action plan.

Image

API Call Flow

Image

Diagnostic Prioritization

1. When top_reason_text is present, pin it to the top and label it Top Opportunity.
2. Display the remaining metrics by the severity of the platform status, but do not present App-defined sorting as an official priority ranking.
3. Within the same severity level, metrics may be sorted by worsening trend, gap to excellent_threshold, or the preference of the responsible operations lead.
4. Place NIL metrics last and explain insufficient data separately.

Optimization Opportunities and Actions

UI Interaction Requirements

• Present the six metrics as switchable tabs or a list; switching metrics must update the value, trend, benchmark, and Action.
• Label the trend chart with both units and the evaluation period; do not show an unlabeled line without axes.
• Use explicit text to indicate whether a lower or higher rate is better; do not rely on color alone.
• When analysis is empty, hide the “Intelligent Analysis” module and do not generate diagnostic conclusions that the platform did not return.

Scenario Overview

Product operations teams may find that NRR or NBFR is dragging down SPS. They need to identify the products with the greatest concentration of issues and the leading negative-review or return reasons, then improve product quality, product detail pages, packaging, and after-sales handling. Primary roles: Product operations, quality owner, and after-sales owner. Successful outcome: The merchant identifies the top affected products and root causes, then completes the appropriate product, packaging, or review-handling actions.

Merchant Flow

The flow below covers NRR / NBFR metric diagnosis, key products, problem orders, and product-action pages. Root causes such as inaccurate descriptions, quality issues, wrong-item shipments, damage, and review handling branch into the appropriate action at the final step.

Image

API Call Flow

Image

Data Mapping

Optimization Recommendations and Actions

UI Interaction Requirements

• Display key products in the order returned by the API and provide a “View problem orders” entry point. Because the API does not define rank, a fixed Top-N, or pagination, do not present the result as a complete ranking.
• Use a placeholder when a product image fails to load; do not block diagnosis.
• Load more must pass through the opaque next_page_token; the client must not parse the token.
• Before an action opens Seller Center, indicate that the merchant is leaving the App and do not claim that the App has completed the change.
• Marking an action complete updates only the App task status; it does not modify SPS API data.

Scenario Overview

Fulfillment operations teams need to reduce seller-fault cancellations and improve the on-time delivery rate. The App frontend should bring inventory, cancellation reasons, expected and actual delivery times, and logistics-provider performance into one diagnostic flow. This helps merchants decide whether to correct inventory, adjust product handling time, extend dispatch deadlines, switch logistics providers, or enroll in FBT. Primary roles: Fulfillment operations, warehouse owner, and logistics owner. Successful outcome: The merchant completes the appropriate inventory or delivery action and can trace the issue to a specific order or logistics provider.

Merchant Flow

The flow below covers SFCR / OTDR diagnosis, cancellation reasons or logistics providers, problem orders, and fulfillment-action pages. Inventory, pricing, SLA, logistics-provider, FBT, and shipping-label actions branch by root cause at the final step.

Image

API Call Flow

Image

Data Mapping

Optimization Recommendations and Actions

UI Interaction Requirements

• In the OTDR logistics-provider table, display the numerator, denominator, and on-time rate clearly; do not sort by order volume alone.
• Do not display an empty “Top Items” module on the SFCR page.
• When expected and actual delivery times are shown together, display the length of the delay.
• The FBT action must state the eligibility requirements and must not promise that historical SPS will change immediately after enrollment.

Scenario

Customer service managers need to identify low-satisfaction chats and slow after-sales requests, determine whether the issues stem from response speed, service attitude, FAQ coverage, manual approval workflows, or return inspections, and configure saved replies, automation, or after-sales rules. Primary roles: Customer Service Manager and After-Sales Manager. Successful outcome: The merchant identifies low-rated chats or high-duration after-sales cases and completes the relevant customer service or after-sales Actions.

Merchant Flow

The diagram below covers IM_DSAT / AHT diagnosis, low-rated chats or after-sales types, handling bottlenecks, and the Service Actions page. At the final node, Actions branch into response speed, service scripts, FAQs, automated approvals, and agent training.

Image

API Call Flow

Image

Data Mapping

Optimization Recommendations and Actions

UI Interaction Requirements

• Use customer names as masked by the API; do not attempt to re-identify them.
• Display only fields within the authorized scope in chat details; do not combine them with personal information from other sources.
• For AHT, show approval, inspection, and total handling times together to help merchants locate workflow bottlenecks.
• Do not display an empty Top Items section on the IM_DSAT page.
• The automated approval Action must remind the merchant to review eligible scenarios and risks.

Scenario

Cross-functional improvements usually cannot be completed in a single diagnostic session. The shop owner needs to assign recommendations in the App to product, fulfillment, or customer service owners, track due dates, and determine whether trends improved after the next SPS update. For merchants who do not proactively open the page, the App can also run periodic monitoring based on update_time and notify them when the SPS tier, Top Opportunity, or benefits status changes. The SPS API is read-only. Tasks, owners, due dates, and completion status must be stored in the App's own system.

Merchant Flow

The diagram below covers the complete journey from converting a recommendation into a task and executing it through an external link, to marking it complete and reviewing it periodically. If new data does not improve, the merchant follows the feedback path back to the diagnosis page and adjusts the Action.

Image

API and App Data Flow

Image

Minimum Action Plan Data Model

Optimization Recommendations and Actions

Periodic Monitoring and Notification Strategy

1. Scheduled jobs should call Overview only. If update_time is unchanged, stop all subsequent calls.
2. After update_time changes, call Metrics and compare score/status/value/top_reason_text with the previous snapshot.
3. Send business notifications only when the SPS tier, Top Opportunity, benefits unlock state, or metric status changes. Avoid creating noise from raw decimal fluctuations.
4. After the merchant opens a notification, lazy-load Diagnosis, Top Items, and Problem Details to avoid continuously fetching and storing order or chat details.
5. The current design has no webhook. The polling frequency must be configurable and comply with the refresh frequency and rate limits in the official API documentation.
6. Need TikTok support: appeal link. Until the link is confirmed, show only guidance for preparing an appeal and hide the empty button.

UI Interaction Requirements

• “Add to Action Plan” and “Go to Seller Center” are two separate actions.
• When the merchant returns after opening an external link, preserve the task's edit state.
• Completing an Action means only that the operational action is complete; it does not mean SPS has improved.
• The follow-up comparison must use a new update_time; otherwise, show “No new data”.

Common host: https://open-api.tiktokglobalshop.com Business headers listed here: x-tts-access-token: <seller_access_token> and content-type: application/json

All five endpoints use GET and send no request body. The table lists endpoint-specific business parameters only; it is not a complete authentication or signing specification. Follow the official OpenAPI documentation for common parameters, signatures, API scopes, error codes, rate limits, and retry policies.

Recommendation Rules

The recommendation engine only interprets and routes results; it does not replace platform scoring. Diagnosis is native API data, while the Action Catalog contains static suggestions that the App matches to diagnosis results. The App frontend must present these two layers separately:

API status/top_reason_text
  + metric_code
  + diagnosis.analysis/distribution
  + reason fields from top_items/problem_details
  -> Match an Action by rule
  -> Merchant confirmation
  -> Seller Center deep link or App-owned task

Recommended priority:

1. Actions for a Top Opportunity metric;
2. Actions that directly match API analysis or an explicit issue reason;
3. Actions that can address a high-share Top Item;
4. General preventive Actions;
5. Show appeal guidance only when the merchant believes the data is incorrect or unfair—not as a default shortcut to a higher score.

Complete Action Catalog (US Primary Flow)

The source recommendation table maintains both L2L and POP links. Because the current SPS API design supports US shops only, this solution includes L2L links in the production primary flow. Enable POP links only after the corresponding market APIs become available.

Page Structure

Image

Core Components

Demo Data Disclaimer

The interaction demo uses mock data to illustrate fields and behaviors. It does not represent any real shop or platform commitment. Thresholds, scores, problem orders, and trends in the demo are for design illustration only; production environments must use actual SPS API responses. Display the following two notices persistently on the page:

• “Data comes from the TikTok Shop SPS API and reflects the most recently calculated result, not real-time monitoring. The benchmark for the current primary category may change with category and peer-merchant performance.”
• “The recommendations below are matched by the App based on API diagnosis results and are provided for operational reference only. Taking an Action does not guarantee changes to the score, traffic, or benefits.”

Mock data notice: All request parameters, response examples, shop/product/order/conversation identifiers, and access-credential examples in this section are mock data provided only to illustrate field formats. They do not represent any real account or business data.

Get SPS Metrics

Request Parameters

Path

Query

Headers

Body (not applicable to GET/DELETE)

Request Body Example

{}

Response Parameters

NIL handling: This example means the individual IM_DSAT metric has not yet met its scoring eligibility conditions. The shop’s overall SPS and other metrics may still be available. The App should show “Insufficient data” only for this metric.

{
  "metric_code": "IM_DSAT",
  "status": "NIL",
  "status_text": ""
}

Note: parameter preceded by ">" means the parameter is a subobject.

{
  "metrics": {
    "benchmarks": {
      "excellent_threshold": "0.02",
      "poor_threshold": "0.08"
    },
    "dimension": "Product satisfaction",
    "evaluate_duration_days": 30,
    "end_evaluation_time": 1761264000,
    "start_evaluation_time": 1758672000,
    "metric_code": "NRR",
    "metric_name": "60-day negative review rate",
    "score": "4.7",
    "status": "EXCELLENT",
    "status_text": "Excellent",
    "value": "0.97",
    "value_unit": "PERCENT",
    "top_reason_text": "Top opportunity"
  }
}

Get SPS Overview

Request Parameters

Path

Query

Headers

Body (not applicable to GET/DELETE)

Request Body Example

{}

Response Parameters

Note: parameter preceded by ">" means the parameter is a subobject.

{
  "benefits": {
    "benefit_name": "LIVE giveaway",
    "is_unlocked": true,
    "unlock_score": "4.5"
  },
  "dimensions": {
    "name": "Product satisfaction",
    "score": "4.8",
    "status": "EXCELLENT",
    "status_text": "Excellent",
    "weight": "70"
  },
  "evaluate_duration_days": 90,
  "end_evaluation_time": 1782518400,
  "start_evaluation_time": 1774828800,
  "peer_percentile": "86.5",
  "primary_category": {
    "category_id": "601450",
    "category_name": "Home Supplies"
  },
  "sps_score": "4.6",
  "sps_tier": "GOOD",
  "sps_tier_text": "Excellent",
  "top_issues": {
    "issues": {
      "description": "Your on-time delivery performance is lower than peer shops.",
      "evaluation_duration_days": 30,
      "end_evaluation_time": 1761264000,
      "start_evaluation_time": 1758672000,
      "metric_code": "OTDR",
      "metric_name": "On-time delivery rate",
      "percentile": "72.4",
      "rank": 1
    },
    "summary": "Improve late dispatch and negative reviews to increase your SPS score."
  },
  "update_time": 1761264000
}

Get SPS Metric Problem Details

Request Parameters

Path

Query

Headers

Body (not applicable to GET/DELETE)

Request Body Example

{}

Response Parameters

Note: parameter preceded by ">" means the parameter is a subobject.

{
  "aht_problem_order_items": {
    "aftersales_type_name": "Only Return",
    "approve_duration_hours": "12.5",
    "inspect_duration_hours": "30.0",
    "order_id": "576461413038785752",
    "return_order_id": "576461413038785753",
    "review_count": 2,
    "total_handle_duration_hours": "42.5"
  },
  "im_dsat_chat_items": {
    "chat_duration_hours": "1.5",
    "chat_record_id": "745961413038785752",
    "customer_name": "J*** D***",
    "customer_rating": 2,
    "first_reply_time": 1761264060,
    "rating_reasons": "other",
    "service_agent": "Agent A"
  },
  "metric_code": "NRR",
  "nbfr_problem_order_items": {
    "deliver_time": 1761523200,
    "order_create_time": 1761264000,
    "order_id": "576461413038785752",
    "product_id": "1729592969712207010",
    "product_name": "Cotton T-Shirt",
    "return_refund_reason": "Wrong size",
    "sku_id": "1729592969712207013"
  },
  "next_page_token": "b2Zmc2V0PTAK",
  "nrr_problem_order_items": {
    "deliver_time": 1761523200,
    "order_create_time": 1761264000,
    "order_id": "576461413038785752",
    "product_id": "1729592969712207008",
    "product_name": "Wireless Headphones",
    "sku_id": "1729592969712207012",
    "user_review_rating": 2
  },
  "otdr_problem_order_items": {
    "actual_deliver_time": 1761609600,
    "expect_deliver_time": 1761523200,
    "order_id": "576461413038785752",
    "product_name": "Wireless Headphones",
    "sku_id": "1729592969712207014"
  },
  "sfcr_problem_order_items": {
    "cancellation_reasons": "Defective item",
    "order_create_time": 1761264000,
    "order_id": "576461413038785752",
    "product_id": "1729592969712207011",
    "product_name": "Smart Watch",
    "sku_id": "1729592969712207014"
  },
  "total_count": 200
}

Get SPS Metric Diagnosis

Request Parameters

Path

Query

Headers

Body (not applicable to GET/DELETE)

Request Body Example

{}

Response Parameters

Note: parameter preceded by ">" means the parameter is a subobject.

{
  "benchmarks": {
    "excellent_threshold": "0.98",
    "poor_threshold": "0.80"
  },
  "calculation_rule": {
    "denominator_label": "Delivered orders",
    "denominator_value": "1000",
    "numerator_label": "On-time delivered orders",
    "numerator_value": "947"
  },
  "dimension": "Product satisfaction",
  "distribution_details": {
    "count": 820,
    "name": "Dispatch 24-48 Hours",
    "percent": "82.0"
  },
  "evaluate_duration_days": 30,
  "end_evaluation_time": 1761264000,
  "start_evaluation_time": 1758672000,
  "metric_code": "OTDR",
  "score": "4.3",
  "status": "GOOD",
  "status_text": "Excellent",
  "trend": {
    "data_points": {
      "record_date": "2026-06-01",
      "value": "0.947"
    }
  },
  "value": "0.947",
  "value_unit": "PERCENT",
  "analysis": {
    "summaries": "",
    "details": ""
  }
}

Get SPS Metric Top Items

Request Parameters

Path

Query

Headers

Body (not applicable to GET/DELETE)

Request Body Example

{}

Response Parameters

Note: parameter preceded by ">" means the parameter is a subobject.

{
  "aht_aftersales_type_items": {
    "handle_duration_hours": "18.5",
    "product_id": "1729592969712207011",
    "product_name": "Smart Watch",
    "return_order_count": 30,
    "top_aftersales_type_name": "Only Refund",
    "top_type_order_count": 20
  },
  "metric_code": "NRR",
  "nbfr_top_product_items": {
    "product_id": "1729592969712207010",
    "product_name": "Cotton T-Shirt",
    "return_order_count": 8,
    "top_reason_order_count": 5,
    "top_return_reasons": "Item doesn't match description"
  },
  "nrr_top_product_items": {
    "delivered_order_count": 300,
    "image_url": "https://example.com/product.jpg",
    "negative_order_count": 12,
    "product_id": "1729592969712207008",
    "product_name": "Wireless Headphones",
    "top_review_reasons": "Item doesn't match description"
  },
  "otdr_logistics_items": {
    "delivered_order_count": 1000,
    "logistics_provider": "TikTok Shipping",
    "on_time_deliver_order_count": 947,
    "on_time_deliver_rate": "0.947"
  },
  "total_count": 120
}