Advertising
The advertising operations read the marketplace ads Nasam captures for a brand on Amazon, noon and Trendyol, and change campaigns on the channel's own ads console. Reads need ads.read; writes need ads.write.
Start with ads coverage: it lists the channels where Nasam can read and change ads for your brands. A channel missing from it has no active connection with ads access, so its campaigns are not captured.
Windows and settled days
Every read with figures takes startDate and endDate, Riyadh calendar days, both inclusive and at most 366 days apart. endDate defaults to today and startDate to 29 days before it. Channels revise recent days as attribution settles, so the latest days can still move. Ads metrics marks each day point with isSettled and returns settledKpis beside kpis; compare periods with settledKpis and previousKpis, not with kpis.
Read performance
curl 'https://api.nasam.co/mm-api/v1/ads/performance?brandIds=20&startDate=2026-09-01&endDate=2026-09-30' \
-H 'accept: application/json' \
-H "Authorization: Bearer $NASAM_API_KEY"
| Question | Operation |
|---|---|
| How is each brand doing on each channel? | Ads performance: one row per brand and channel with spend, attributedSales, settledRoas and belowFloorShare, plus totals. |
| What are the KPIs and how do they trend? | Ads metrics: kpis, a point per day, and byChannel, which always adds up to kpis. |
| Which campaigns are spending, and how? | List campaigns, filtered by adTypes, targetingModes, statuses or search. |
| Which products does a campaign spend on? | List campaign items, with atRiskOnly=true for the items whose spend is at risk. |
| Is a brand's ads return healthy? | Ads brand health: a band per brand, judged over the 30 days ending at the last settled day. |
| How much prepaid balance is left? | Ad wallet. The body is null on a channel that bills a card, such as Amazon. |
ROAS judges conversion campaigns only. settledRoas is null on a campaign whose objective is not Conversion and at zero spend; such a campaign reports the channel's own figure in nativeSuccessMetric. The campaign list returns roasFloor, the line a conversion campaign is judged against, and belowFloorShare is the share of spend that returned under it.
A figure the channel never reports at that level is null, not 0. A campaign's reports says which ones apply: hasAtc for add-to-cart, hasItemMetrics for figures per product, hasBuyBox for Buy Box state on its items.
Spend risks
Each campaign item carries spendRisks, the reasons its spend may not turn into sales: LowRating, FewReviews, BuyBoxLost and LowDaysOfStock. The list returns spendRiskLines with the thresholds behind them, so you can state why an item is flagged. Risks are flagged only on an Active item matched to a listing that spent in the window.
Change a campaign
Writes reach the channel's console before Nasam records them, so a refusal from the channel fails the request and nothing changes. Send an Idempotency-Key on every write so a retry is safe.
| Change | Operation |
|---|---|
| Create a campaign | Create campaign with brandId, saleChannelId, family, budgetType, budgetAmount, startDate and the seller SKUs in itemSkus. |
| Pause, resume, rename, change budget, end date or settings | Update campaign. Send only what changes; settings merge into the current ones. |
| Advertise more products | Find SKUs with ads catalog, passing excludeCampaignId to skip what the campaign already advertises, then add campaign items. |
| Stop advertising a product | Exclude campaign item. The item stays in the list as Excluded. |
settings holds only the levers the campaign's type has, such as bidStrategy, defaultBid, keywords or a brand creative; a lever the type lacks is absent. Read the campaign again after a write: it returns the campaign as Nasam now holds it.
Ad fees the channel deducts from payouts also appear in profitability as transactions. The advertising operations report what the ads console states; profitability reports what the statement settled.