Skip to main content

Profitability and settlements

Profitability follows money the channel has recorded: revenue, fees, cleared value, settlement statements, and product cost. Start with a fixed brand and date window, inspect the money summary, then follow a statement into its transactions or a product into its receipt. For order and product activity before settlement, use sales performance. Retail purchase orders have a separate lifecycle guide.

Choose the financial read​

QuestionRead
What did the channel clear after its transaction groups?Money summary
Which statement arrived, and does its declared total match captured transactions?Settlements and settlement detail
Why does a product appear profitable or loss-making?Product receipt and its cost coverage

Read money for a fixed scope​

Profitability reads use startDate and endDate as inclusive Riyadh calendar days in YYYY-MM-DD form. A brandIds filter narrows the caller's scope, and saleChannelIds can narrow further. Money describes revenue, cleared amount, units, and transaction groups per currency. It does not add amounts across currencies or silently subtract product cost from cleared. Tax transactions are shown as a group but excluded from cleared money.

Start a reconciliation with a fixed scope and window:

curl --get 'https://api.nasam.co/mm-api/v1/profitability/money' \
--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"

Read currency before displaying an amount. keepRate is cleared ÷ revenue when revenue is positive; netAfterCost needs cost coverage for every settled line in scope. A null value is an unavailable calculation, not a zero result. Inspect groups to explain the cleared amount, and unattributed when money cannot be assigned to a listed product. A no-signal response needs its noSignalReason interpreted before charting zero activity.

Brand rankings and product rankings page through the chosen window. Keep-rate distribution describes the whole filtered population, so a table page can be selected from a histogram bin. Trends requires a calendar granularity and can split by dimension; a split trend caps its row count separately from a paginated ranking. A keep rate is cleared ÷ revenue where revenue is positive, and can be null when the ratio has no meaning.

Settlements list statements by the channel's statementDate; one settlement compares its declared amount with the transactions captured for it. Transactions show the signed ledger at settlement or brand scope. A missing or incomplete statement total is different from a zero amount. Use the product receipt to inspect one product's settled economics and cost coverage; missing cost or unattributed money can prevent a meaningful profit assertion.

For a statement discrepancy, page settlements in the same window and select its settlementId. The detail returns declaredTotal and transactionsTotal with currency; either total can be null while source data is incomplete. Then page transactions with that settlementId and the same required startDate and endDate. Inspect signed amounts and transaction groups before declaring a difference. The statement's date and covered period can differ, so preserve statementDate, periodStart, and periodEnd as separate concepts.

curl --get 'https://api.nasam.co/mm-api/v1/profitability/transactions' \
--data-urlencode 'settlementId=123' \
--data-urlencode 'startDate=2026-09-01' \
--data-urlencode 'endDate=2026-09-30' \
--data-urlencode 'page=1' \
--data-urlencode 'limit=25' \
-H 'accept: application/json' \
-H "Authorization: Bearer $NASAM_API_KEY"

Product costs are maintained in the Nasam app, where a cost file runs as a tracked import under Data → Imports. Target margin is a product-level decision; accepted loss classifies chosen listings. Both writes change how losses are interpreted, not the channel's financial transaction history.

After a cost upload, re-read the product receipt for the same date window. If its cost coverage is still incomplete, check the product's listing mapping, and ask the brand to fix the rejected rows of its cost import in the app, before presenting a margin. A target margin or accepted-loss decision records how the business evaluates a product or listing; neither changes the underlying settlement.

Rank products by parent​

A parent is one design sold in several sizes or colours, each a variant with its own SKU. Every ranked product carries parentKey, null when it has none.

Pass groupBy=parent to product rankings to page through items: a parent is one item and a product with no parent is one item, each at one account brand and one currency, so currencies never mix. limit and pagination.total count items. search, productIds and state match variants, and a parent is on the page when any of its variants matches; minKeepRate and maxKeepRate apply to the parent's own keep rate. products holds the matching variants, contiguous per item, each with variantLabel and variantLabelAR. parents carries each parent in page order with units, revenue, fees, cleared, keepRate and keepRateAfterCost over its variants in scope, and variantStates, how many variants have a channel in each listing state. A row belongs to the parent with the same parentKey, brandId and currency.

Send the same groupBy=parent to keep-rate distribution so its bins bucket parents on their own keep rate and count items, matching the grouped table. A parent's keep rate can look healthy while one size bleeds: each variant keeps its own channels, keep-rate band and listing state, so read variantStates.Bleeding before treating a parent as healthy.