Ecommerce Ozon Brand Products Skill for Claude

Nexscope Ozon Brand Products

This skill drills into all Ozon (Russia) products sold under a given brand display name, returning each SKU's sales, revenue, price, rating, stock, turnover, lost profit, and more. Built for brand competitor audits, brand SKU structure analysis, and bestseller dissection.

Core Concepts

Brand display name: brandName must match what's shown on the Ozon storefront — typically Russian (Cyrillic) or Latin (adidas, Xiaomi). Do not pass a category path, a seller ID, or an internal brand code here. If unsure of the exact spelling, resolve via ecommerce.ozon-product-search first.

Filters are AND-combined: The filters array supports multiple numeric conditions ANDed together. Each filter is {field, op, value, value2?}. Common fields and operators are in the Filter Reference below.

Currency & rate: Default currency is RUB. Set currency: "USD" (or another code) to have monetary fields converted server-side; currencyRate lets you override the default rate if desired.

FBO / FBS mix: includeFbs: true folds FBS (seller-shipped) stock + sales into the numbers; false keeps them FBO-only.

Parameters

| Parameter | Type | Required | Description |

|-----------|------|----------|-------------|

| brandName | string | yes | Ozon brand display name (Russian or Latin) |

| startDate | string | no | Stats window start, YYYY-MM-DD; latest = yesterday |

| endDate | string | no | Stats window end, YYYY-MM-DD; latest = yesterday |

| page | integer | no | Page number, starts at 1 |

| pageSize | integer | no | Rows per page, 1-100, default 100 |

| sortField | string | no | snake_case column: sales, revenue, final_price, balance, rating, ... |

| sortDirection | string | no | asc or desc |

| currency | string | no | Currency code, default RUB; e.g. USD, EUR, CNY |

| currencyRate | integer | no | Custom rate when non-default currency is used |

| includeFbs | boolean | no | Include FBS data |

| filters | array | no | Numeric filter conditions (see below) |

Filter Reference

Each filters entry: {"field": "<snake_case>", "op": "<OP>", "value": <num>, "value2": <num?>}.

Common fields: sales (monthly units), final_price (selling price RUB), rating (0-5), comments (review count), balance (stock), revenue (sales amount RUB), days_in_stock, turnover_days, lost_profit, category_position.

Operators: GTE, LTE, GT, LT, EQ, NOT_EQ, BETWEEN (requires value2 as the upper bound).

Calling the Tool

• API Endpoint: /mpstats/ozon/brandProducts (full parameters/responses/error codes in references/api.md)
• Python Script: python scripts/ozon_brand_products.py '<JSON params>' [--inline]
• Cost constraint: This tool consumes credits. Within the same session and same parameter combination, it defaults to a single call with a 24-hour local cache. Do not automatically retry with different keywords, pagination, or parameters on failure/empty results. Inform the user of additional credit consumption before continuing retrieval.

Output strategy (script default behavior):

• Always write the full response to <cwd>/nexscope/<YYYY-MM-DD>/<session>/data/ecommerce.ozon-brand-products-<timestamp>.json (<cwd> is the working directory when the script executes, which in Claude Code is the current project directory; <session> is taken from the SESSION_ID environment variable, automatically grouped by user task; do not write to /tmp; error if the current directory is not writable)
• Response body <= 8 KB: write to disk then print full JSON to stdout
• Response body > 8 KB: write to disk then print only a summary to stdout (top-level fields, common counts like total/costToken, length of the largest list field + first 3 samples)
• Add --inline to force full output to stdout (still writes to disk)

Reading data: Check the summary first to determine if it is sufficient. When specific fields are needed, use jq or ConvertFrom-Json to extract from the saved JSON file as needed, avoiding loading the entire JSON into context.

Authentication & Credits

If you encounter authentication or credit issues:

Error conditions

• API Key not configured: The NEXSCOPE_API_KEY environment variable is not set.
• HTTP 401 or 402 status code
• Insufficient credits/balance: Response message indicates credit balance exhausted, quota exceeded, subscription expired, or recharge required.

Resolution steps

• Set the NEXSCOPE_API_KEY environment variable with a valid API key.
• If credits are insufficient, visit https://www.nexscope.ai/pricing?co-from=skillNS to top up your balance.
• For onboarding and setup guidance, refer to https://www.nexscope.ai/help/skills-external-access?co-from=skillNS

Usage Examples

1. Top-50 by sales for brand adidas

{
  "brandName": "adidas",
  "sortField": "sales",
  "sortDirection": "desc",
  "pageSize": 50
}

2. High-rating, mid-price filter

{
  "brandName": "Xiaomi",
  "filters": [
    {"field": "rating", "op": "GTE", "value": 4.5},
    {"field": "final_price", "op": "BETWEEN", "value": 1000, "value2": 5000}
  ],
  "sortField": "revenue",
  "sortDirection": "desc"
}

3. USD-converted output

{
  "brandName": "Nike",
  "currency": "USD",
  "sortField": "revenue"
}

4. Include FBS + only in-stock items

{
  "brandName": "adidas",
  "includeFbs": true,
  "filters": [{"field": "balance", "op": "GT", "value": 0}]
}

5. Lost-profit hunters (out-of-stock pain)

{
  "brandName": "Nike",
  "filters": [{"field": "lost_profit", "op": "GTE", "value": 100000}],
  "sortField": "lost_profit",
  "sortDirection": "desc"
}

Display Rules

• Compact brand table — key columns: productId, title, price, monthlySalesUnits, monthlySalesRevenue, rating, reviewCount, balance, turnoverDays, lostProfit.
• Revenue share context — revenueSharePercent is the SKU's share within this brand result set, 0-100; clarify the base when presenting.
• Currency labeling — always state the currency in the table header; if currency was overridden, note "converted to USD".
• Russian titles — preserve original; translate on user request.
• Pagination — report total and guide the user to next page or narrower filters when total exceeds the returned page.
• No business advice — present the data; don't project future sales from a snapshot.

Important Limitations

• Exact brand-name match — no fuzzy search; typos return empty results. Verify via ecommerce.ozon-product-search if unsure.
• Page cap — max 100 rows per page; paginate for larger brands.
• Date window — endDate cannot be today or a future date (T-1 data).
• Currency conversion — server-side; historical rates may differ slightly from the user's reference rate.
• Russian-only titles — translate only when asked.

User Expression & Scenario Quick Reference

Applicable — Brand-scoped Ozon product metrics:

| User Says | Scenario |

|-----------|----------|

| "Show me adidas's top-selling Ozon SKUs" | Brand bestseller drill |

| "What does Xiaomi sell on Ozon, sorted by revenue" | Brand revenue structure |

| "Which brand-X SKUs have rating ≥4.5 and stock >0" | Brand quality filter |

| "Are brand-X's stockouts causing big lost profit" | Lost-profit hunter |

| "Convert brand-X's Ozon sales to USD" | Currency-normalized audit |

Not applicable — Needs beyond brand drill-down:

• Unknown exact brand name → first use ecommerce.ozon-product-search
• Category-level comparison across brands → use ecommerce.ozon-category-products
• Seller-scoped analysis → use ecommerce.ozon-seller-products
• Single-SKU time-series → use ecommerce.ozon-product-trend
• Wildberries / other Russian marketplaces → not covered

Boundary judgment: Use this skill when the question centers on one brand and you want the per-SKU rollup under it. For "which brand dominates category X" use category drill-down and compare brand rows server-side.