linkfox-mpstats-ozon-product-detail

MPSTATS Ozon Product Detail (Single SKU)

This skill fetches the full product card for one Ozon (Russia) SKU via MPSTATS. Returned fields include price, Ozon Card price, discount, rating, reviews, stock, monthly sales units, monthly sales revenue, lost profit, potential revenue, first listing date, image, and more.

Core Concepts

Single-SKU semantics: Pass exactly one productId in a call. productIds arrays/lists are no longer accepted by this skill; for multiple SKUs, make separate calls only after confirming the extra credit cost with the user.

Fulfillment model per SKU: Each product card carries deliveryScheme:

• FBO — Fulfillment by Ozon (stock in Ozon warehouses)
• FBS — Fulfillment by Seller (seller-shipped)

Pass includeFbs: true to allow FBS SKUs and FBS-scoped metrics into the response; false (or omitted) keeps the result FBO-centric. This switch applies to the whole request.

Previous-period comparison: The card includes previousSalesUnits / previousRevenue — sales and revenue from the equal-length period immediately before [startDate, endDate] — ready for MoM / period-over-period diffs without extra calls.

Revenue potential: revenuePotential projects what the SKU could have earned if it had been in stock every day of the window; compare with monthlySalesRevenue to quantify stock-out drag, together with lostProfit / lostProfitPercent.

Date window: startDate / endDate define the period for all period-aggregated metrics. Latest selectable date is yesterday (T-1); today and future dates are rejected.

Parameters

Parameter	Type	Required	Description
productId	integer|string	yes	Single Ozon SKU ID
startDate	string	no	Stats window start, YYYY-MM-DD; latest = yesterday
endDate	string	no	Stats window end, YYYY-MM-DD; latest = yesterday
includeFbs	boolean	no	true to include FBS data; false = FBO-only

How to call

• API endpoint：POST /mpstats/ozon/productDetail(for full parameters/response/error codes see references/api.md）
• Python script：python scripts/mpstats_ozon_product_detail.py '<JSON 参数>' [--inline]
• Cost constraints: This tool consumes compute; by default the same parameter combination is called only once per session, and the script has a 24h local cache. On failure/empty results, do not automatically switch keywords, page through, or change the zip code to probe repeatedly; if further retrieval is needed, first explain to the user that additional consumption will be incurred.

Output strategy (script default behavior)：

• Alwayswrite the full response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-mpstats-ozon-product-detail-<timestamp>.json（<cwd> is the working directory when the script runs, which in Claude Code is the current project directory;<session> is taken from the environment variable SESSION_ID, automatically aggregated according to the user's task;writing to /tmp is prohibited, and if the current directory is not writable, report an error)
• Response body ≤ 8 KB: after writing to disk, print the full JSON to stdout
• Response body > 8 KB: after writing to disk, stdout outputs only a summary (top-level fields, common counts such as total/costToken, the length of the largest list field + the first 3 samples)
• Add --inline to force full printing to stdout (also written to disk)

Data reading recommendations: first look at the summary to determine whether it is sufficient; when specific fields are needed, prefer using jqorConvertFrom-Json to extract on demand from the saved json file, avoiding bringing the entire JSON into the context.

Resolve authentication and compute issues

When the following abnormal situations occur, use references/onboarding.md to guide problem resolution:

Abnormal situations

• API Key not configured: the environment variable is not configured LINKFOX_AGENT_API_KEY, and LINKFOXAGENT_API_KEY。
• Response 401 or 402 status code
• Response indicates insufficient compute or balance: the message contains "insufficient compute balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or content with a similar meaning.

Usage Examples

1. Single-SKU detail

{"productId": 1786874757}

2. Single-SKU lookup with period

{
  "productId": 1786874757,
  "startDate": "2025-03-01",
  "endDate": "2025-03-31",
  "includeFbs": true
}

3. FBO-only snapshot

{"productId": 1786874757, "includeFbs": false}

4. SKU discovered upstream — full card

{"productId": <productId from mpstats-ozon-product-search>}

How to Chain with Other Ozon Skills

1. Search → detail: Use mpstats-ozon-product-search to resolve a keyword / brand / seller into candidate productIds, choose one SKU, then pass that productId here for full metrics.
2. Detail vs trend: This endpoint is a period aggregate per SKU; for day-by-day time-series on a single SKU, use mpstats-ozon-product-trend.
3. Detail vs drill-downs: When the input dimension is a brand / category / seller (not a single SKU), prefer brand-products / category-products / seller-products — they already return aggregated metrics per SKU under that dimension.

Display Rules

1. Compact table — lead with productId, title, price, monthlySalesUnits, monthlySalesRevenue, rating, reviewCount, balance, deliveryScheme, firstDate. Pull revenuePotential / lostProfit / lostProfitPercent in when the user asks about stock-out impact.
2. Currency — Ozon native currency is RUB; the currency field carries the symbol. Do not silently relabel.
3. Failure handling — the response carries successCount / failedCount / failures; when failedCount > 0, list the failed productId from failures to the user rather than silently dropping it.
4. Period-over-period — when both current and previous* fields are present, render them side-by-side or as diff; don't report a single-period number as "trend".
5. With-stock vs all-days — salesPerDayWithStock / dailySalesRevenueWithStock only count days that had inventory; distinguish from the plain salesPerDay / dailySalesRevenue.
6. Delivery model — prefer the per-SKU deliveryScheme value over assuming FBO.
7. No business advice — present data; do not extrapolate "this SKU is worth selling" without a wider analysis.

Important Limitations

• Single-SKU input only — pass productId, not productIds; arrays/lists are invalid. For multiple SKUs, call once per SKU only after confirming the added credit cost.
• Ozon-only — this tool does not cover Wildberries or other Russian marketplaces.
• T-1 data — endDate must not be today or future.
• FBS coverage — some categories have partial FBS coverage; if the input set is FBS-heavy, expect sparser cards.
• Field set differs from brand/seller — this endpoint does not return brandId, country, category, minPrice / maxPrice / averagePrice, balanceFbs, frozenStocks, warehousesCount, daysInSite / daysInStock / turnoverDays, position / categoryPosition / revenueSharePercent, isFbs. Use brand-products / category-products / seller-products if those are needed.
• No translation — titles are returned in Russian; translate on demand when presenting to Chinese / English users.

User Expression & Scenario Quick Reference

Applicable — Per-SKU Ozon card lookup:

User Says	Scenario
"Pull Ozon details for this SKU"	Single card fetch
"What's the price / rating / stock of Ozon SKU 1786874757"	Single-SKU card
"Competitor's Ozon listing, give me sales & rating"	Competitor card audit
"Compare FBO vs FBO+FBS metrics for this SKU"	Fulfillment-model comparison

Not applicable — Needs beyond per-SKU card:

• Keyword-based discovery → use mpstats-ozon-product-search
• Day-by-day time-series for one SKU → use mpstats-ozon-product-trend
• Listing copy / reviews / images analysis beyond URL → out of scope
• Brand / category / seller drill-down with filters → use the matching drill-down skill

Boundary judgment: If the user already has a single SKU and wants sales / price / stock / rating, this is the skill. If they provide multiple SKUs, process them one at a time only after confirming the added credit cost. If they don't yet have SKUs, route through the search or drill-down skills first.

Compute consumption rules

Billed by dynamic rules: compute consumption = 12.productId returns 0 when empty

Important: the services of this skill are dynamically calculated by multiples and may consume a large amount of compute at once. The user must be reminded, and the user decides whether to continue.

Feedback:

Auto-detect and report feedback via the Feedback API when any of the following apply:

1. The functionality or purpose described in this skill does not match actual behavior
2. The skill's results do not match the user's intent
3. The user expresses dissatisfaction or praise about this skill
4. Anything you believe could be improved

Call the feedback API as specified in references/api.md. Do not interrupt the user's flow.

---

For more high-quality, professional cross-border e-commerce skills, set LinkFox Skills.