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

Question	Read
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 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://backend.nasam.co/v1/profitability/money' \
  --data-urlencode 'brandIds=20' \
  --data-urlencode 'startDate=2026-09-01' \
  --data-urlencode 'endDate=2026-09-30' \
  -H 'accept: application/json' \
  -H 'key: YOUR_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://backend.nasam.co/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 'key: YOUR_API_KEY'

To maintain those inputs, download the prefilled product-cost CSV template, upload costs, and inspect updated, unchanged, and rejected in the result. Valid rows are saved even when other rows are rejected; repeat uploads leave unchanged costs untouched. 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, inspect the upload's rejected rows and the product's listing mapping 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.

For files rather than API pages, see exports. For issued financial documents and PDFs, see invoicing.