Brand Health API

Brand Health brings marketplace operations into one view per brand. Use it to find where a team needs to act, understand the evidence behind a status, and move from a summary to the affected orders, products, reviews, or inventory. Each brand has nine dimensions. A dimension reports a band, the time it entered that band, and an English and Arabic offending fact when one is available.

Start with list brand health summaries to see every brand in your scope. Then get one brand's health for its current dimension details and history30d. Brand Health is a read of Nasam's operational assessment; it does not change orders, inventory, pricing, or campaigns.

Triage a brand from signal to outcome

1. Find the affected brand. Read GET /v1/brand-health/brands. Use counts for the size of the dimension-level action queue, then inspect each brand's dimensions[]. Choose a brand with NeedsAction or Slipping; use hasUnread to identify a new unhealthy entry for the calling user. A NoSignal cell needs an availability check, not an operational fix.
2. Open the dimension detail. Read GET /v1/brand-health/brands/{brandId}. Match the summary's dimension value to the detail key in the table below. Read band, noSignalReason, offendingFactEn, and bandEnteredAt before using the dimension's snapshot. bandEnteredAt dates the current classification, not the last capture.
3. Follow the evidence. Use the dimension's linked drilldown for the affected orders, products, or purchase orders. Pass a channel or product filter only if that drilldown supports it. The detail snapshot gives context; a paged drilldown supplies the rows to investigate and should be paged independently.
4. Act in the owning workflow. For example, process an overdue order through the orders and fulfillment guide, investigate stock through the inventory guide, or work a pending purchase order through the vendor purchase order guide. Brand Health's seen state records review; it does not carry out those actions.
5. Verify the outcome. Read the same brand detail again after the underlying data has been captured and assessed. Compare the new band and history30d with the prior reading. A source metric can recover before an unhealthy band clears because exit from an unhealthy band passes through a cooldown. Do not infer completion from hasUnread: false.

The list has no pagination parameters. Its counts cover dimension cells across the brands in scope, while each drilldown has its own filters and pagination. Keep those scopes separate when building a queue or dashboard.

The nine dimensions

Dimension in the detail response	What to inspect	Related evidence
fulfillment	Fulfillment performance by sale channel and fulfillment model; its channels snapshot includes metric and account status details.	Unprocessed orders, rejections
inventory	Availability and stock exposure by destination; destinationSummaries and firstPage summarize the current inventory signal.	Inventory SKUs
listings	Listing health band, explanation, and history. This dimension has no separate computed metrics snapshot.	Brand detail
buyBox	Eligible and lost Buy Box counts, with a channel breakdown.	Lost Buy Boxes, pricing risks
reviews	Channel review signals and recently negative reviews.	Review products, rated products, negative reviews
cancelsReturns	Cancellation and return rates, recent trend, reasons, and affected products.	Cancel and return products
vendor	Requested, accepted, and received units, plus acknowledgement and delivery work in the selected window.	Pending vendor work
inbounds	Planned, landed, and good units; fill and landing rates; open discrepancies and units at risk.	Brand detail
profitability	Revenue, cleared value, keep rates, and products losing money by channel.	Pricing risks

These are the keys in a brand detail response, such as buyBox and cancelsReturns. The summary response instead places each dimension in brands[].dimensions[] with a dimension value such as BuyBox or CancelsReturns.

Read the band before acting

Band	Meaning for a consumer
NeedsAction	The current signal crosses the action threshold. Read offendingFactEn or offendingFactAr and the relevant drilldown.
Slipping	The signal has deteriorated but has not reached the action band. Watch the evidence and trend.
Healthy	Available evidence meets the healthy threshold.
NoSignal	There is no usable assessment for this dimension. It is not a healthy result. Inspect noSignalReason.

noSignalReason is one of NotApplicable, NotIntegrated, AwaitingSync, or InsufficientData when the band has no signal. A missing or stale current health row is returned as NoSignal with AwaitingSync. Nasam treats a row older than seven days as stale. Snapshot fields can be absent on a no-signal detail, so branch on band before reading a dimension's metrics.

noSignalReason	How to handle it
NotApplicable	The dimension does not apply to this brand or channel. Exclude it from an action queue.
NotIntegrated	The required source is not connected or supported for this signal. Check the relevant sale channel connection before interpreting the absence as performance.
AwaitingSync	The assessment is missing, stale, or waiting for source data. Check Sync Health, then read the brand again after capture and assessment.
InsufficientData	There is not enough eligible evidence to classify the dimension. Keep the cell visible as unknown; do not fill absent rates with zero.

For example, the listings portion of a brand detail can have no signal and no metrics snapshot:

{
  "dimension": "Listings",
  "band": "NoSignal",
  "bandEnteredAt": null,
  "noSignalReason": "AwaitingSync",
  "offendingFactEn": null,
  "offendingFactAr": null,
  "history30d": []
}

bandEnteredAt tells you when the current band began; it is not a last-sync timestamp. history30d contains recorded { day, band } entries from the last 30 days. It can contain fewer than 30 entries. A move into an unhealthy band is immediate; clearing it can wait through a cooldown, so a healthy source metric and the reported band need not change in the same instant.

The list's counts.needsAction and counts.slipping count dimension cells across the returned brands. They do not count unique brands. Each brands[] item also has hasUnread for the calling user. The unread marker follows the latest unhealthy band entry; mark seen or mark unread when your workflow needs to acknowledge or revisit a brand. Both return HTTP 204.

After reviewing a brand, an operator can acknowledge it without changing its health classification:

curl -fsS -X PATCH "https://backend.nasam.co/v1/brand-health/brands/20/seen" \
  -H "key: $NASAM_API_KEY"

Use PATCH /v1/brand-health/brands/{brandId}/unread to put it back in the review queue. Neither action confirms that the underlying issue has been resolved. Confirm resolution by reading the dimension again, and continue to display NoSignal as unknown even after the review state changes.

Read a brand and its evidence

The following requests use a key stored in NASAM_API_KEY and a brand ID from list brands.

curl -fsS "https://backend.nasam.co/v1/brand-health/brands" \
  -H "key: $NASAM_API_KEY" \
  -H "Accept: application/json"

curl -fsS "https://backend.nasam.co/v1/brand-health/brands/20" \
  -H "key: $NASAM_API_KEY" \
  -H "Accept: application/json"

Read band and noSignalReason for each dimension before using its snapshot. For example, a buyer can inspect buyBox.losingCount and buyBox.perChannel, then page through the underlying lost Buy Boxes. A fulfillment team can inspect fulfillment.channels and fetch unprocessed orders.

curl -fsS --get \
  "https://backend.nasam.co/v1/brand-health/brands/20/lost-buy-boxes" \
  -H "key: $NASAM_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "saleChannelIds=12" \
  --data-urlencode "categories=Oils, Sauces & Spices" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=25"

Drilldowns have their own filter sets and page-size limits; open the linked operation before reusing a query across resources. Where supported, saleChannelIds and productTiers are comma-separated lists. Repeat categories for multiple category names, since a name can itself contain a comma. Rejections require kind=cancel or kind=return. Unprocessed orders accept includeOlder=true to include overdue orders in the returned rows. For inventory SKUs, take destinationKey from inventory.destinationSummaries[].destination.key in the detail response.

Advertising health is available through advertising health cells. Those cells are a separate Ads resource; the Brand Health detail above has the nine named dimensions shown in this guide.