Skip to main content

Sales and product performance

Sales reports describe order and product activity. Start with an overview for a fixed brand and time window, compare two periods, then inspect the products and listings behind a change. If you need cleared money, fees, statements, or cost coverage, follow the separate profitability guide. Retail supply has its own vendor purchase order lifecycle.

Investigate a sales change​

Home supplies a dashboard aggregate. Overview returns sales performance for an optional brand and date selection; omitted brandIds use the caller's accessible brands. Period comparison requires both start and end dates for each of its two periods. These aggregate responses are distinct from paginated catalogs.

Home also carries concerns, Nasam's verdict on sales, growth, profit, ads and operations (Calm, Warning, Bad, or Failed when a source behind it could not be read; null when the concern does not apply to the scope or the caller may not read it), and relevance, which says whether the scope sells on storefronts, to retailers, or both. ads covers the 30 days ending three days before today, so ad attribution that is still landing is not judged, and is null when sources.ads is not Ok: the caller lacks ads.read or no campaign ran in that window. pulse.orderWork.overdueLead names the brand with the most overdue shipments. retail.received covers the 30 closed days before today, the same days as pulse.last30d, so the two can be added; its window states the exact dates. pulse.traffic counts product page views on the channels that report them, and conversionRate is the orders on the same brands, channels and days divided by those page views. Channels send page views a few days late, so its window is the latest seven days every counted channel has reported, and a channel more than three days behind is left out. It is null when no channel in scope has reported page views in that time.

To investigate a fall in sales, first fix the brand and calendar window, then compare it with a second explicit window. This avoids confusing a different brand mix with a time trend:

curl --get 'https://api.nasam.co/mm-api/v1/overview' \
--data-urlencode 'brandIds=20' \
--data-urlencode 'startDate=2026-09-01' \
--data-urlencode 'endDate=2026-09-30' \
-H 'accept: application/json' \
-H "Authorization: Bearer $NASAM_API_KEY"

The overview includes order counts, revenue, units, trend, stock alerts, channel share, and product performers. Use period comparison for two chosen windows; provide p1StartDate, p1EndDate, p2StartDate, and p2EndDate together. Use product performance when an aggregate change needs a product and channel explanation. These are sales activity views, so do not use their revenue alone as a payout or margin figure.

Compare like scopes before naming a cause​

Use the same brand, category, tier, and channel exclusions in both periods. The comparison operation accepts both windows in one request:

curl --get 'https://api.nasam.co/mm-api/v1/overview/period-comparison' \
--data-urlencode 'brandIds=20' \
--data-urlencode 'p1StartDate=2026-09-01' \
--data-urlencode 'p1EndDate=2026-09-30' \
--data-urlencode 'p2StartDate=2026-08-01' \
--data-urlencode 'p2EndDate=2026-08-31' \
-H 'accept: application/json' \
-H "Authorization: Bearer $NASAM_API_KEY"

The date fields identify two explicit periods; they are not a request for a rolling comparison. Keep those request windows beside the returned p1, p2, and growth values when displaying a percentage change. A change in orders, average order value, or units suggests different next reads; the overview alone does not attribute a cause to a product, listing, or channel.

Find the products behind the movement​

Product performance returns one product's trends and channel breakdowns. Without a date window, the service uses the latest 30 days including today. Product period comparison compares two explicit windows. Top performers, declining, growing, and period metrics answer different list questions. Top performers can split by product, listing or parent; its default page=2 is intentional because the overview supplies the first set. Follow each operation's filters and response shape instead of treating these reads as interchangeable.

Each entry in product performance's listings carries the listing's content counts, the same as listing detail returns, so a listing that sells less than its siblings can be read beside what its content meets.

InvestigationReadHow to use it
Which products contribute the most in one window?Top performersPass page=1 when building a standalone first page; its omitted-page default follows the overview's embedded first set.
Which products lost or gained momentum between two windows?Declining or growingSupply both periods and keep the same brand and channel scope as the overview comparison.
Did one product move differently across channel listings?Product performance, reading its listingsPerformance and listingsUse its product ID from the catalog or report; inspect the listing and channel context before taking a catalog or stock action.
Do you need a small set of period totals for a dashboard?Period metricsSupply its required start and end dates; do not substitute a paginated product ranking.

The report operations can exclude sale channels with excludeSaleChannelIds. Profitability instead filters included saleChannelIds; the two families should not be sent the same query string without translating the selection. If a listing has stale captured data, read Sync Health before interpreting a sudden product change. Catalog review and inventory planning are the next workflows when the evidence points to listing mapping or stock availability.

Rank by parent​

A parent is one design sold in several sizes or colours, each a variant with its own SKU. ByProduct rows of top performers, declining and growing, and the declining and growing products in period comparison, carry parentKey, null for a product with no parent. Rows sharing a key are variants of one parent.

Pass performanceBreakdown=ByParent to the three ranking reads to rank parents on their variants' sums. page and limit count items. A parent row has parentKey, parent (its key, shared name, imageUrl and variantCount) and variants, and no product; a product with no parent is a row with parentKey: null, its product, and variants holding that one product. Branch on parentKey to tell them apart.

On top performers, totalRevenue, unitsSold and saleChannelBreakdown sum the variants with sales in the window, and variants lists them by revenue. On declining and growing, the period sums, revenueDelta and growthPercentage are the parent's, isOutOfStock is true only when every variant in scope is out of stock, and variants lists every variant in scope by p1 revenue with its own figures in both periods. A parent can grow while one size declines, so read variants before acting on one SKU.

Product performance for a variant returns parent with every variant of its parent and each one's catalog stock, units and revenue; it is null for a product with no parent.