Sync Health
GET /v1/sync-health/brands/{brandId} tells you whether Nasam is receiving and processing the brand's connected-channel data. Read it after discovering the brand and account IDs. It reports a brand state, a channels array, and brandWide sync status. The brand headline reflects its worst channel or brand-wide problem; inspect the child records to find the cause.
Each channel has a saleChannelAccountId, channel identity, connectionState, overall state, and streams. connectionState is Connected, Connecting, ConnectionFailed, or AuthExpired. A stream has a key, state, reason, and lastSyncedAt; inventory can also include drift with observed and drifting listing counts. lastSyncedAt is meaningful for a freshness stream and can be null before a first success.
Triage a stale channel before using its data
curl 'https://backend.nasam.co/v1/sync-health/brands/20' \
-H 'accept: application/json' \
-H 'key: YOUR_API_KEY'
Use a brand ID from list brands. Locate the affected account by saleChannelAccountId, then read its connectionState and each stream's state and reason. The headline state is the worst child state, not a guarantee that every stream has the same problem. brandWide covers work that belongs to the brand rather than one channel, such as planning or health recomputes.
| What you see | What it means | Next check |
|---|---|---|
Connecting or Setup | The connection is still being established. | Read the connected account before treating an empty stream as lost data. |
ConnectionFailed or AuthExpired | The account cannot currently provide reliable channel data. | Follow the connection lifecycle for the affected account. |
Listings Lagging or Problem with Overdue | The most recent successful listing capture is beyond that stream's cadence. | Compare lastSyncedAt with the time of the business decision; check the listing review queue if the reason is DataIssue. |
Inventory Drifting | Channel-observed quantity differs from Nasam's last pushed quantity on observed listings. | Inspect drift.observedListings, drift.driftingListings, and drift.observedAt, then preview a drift resync. |
Orders or POs Problem | A capture run failed. | Hold downstream automation for that stream and investigate its reason; the POs stream applies only to retail channels. |
Returns Lagging | Post-sale capture failed. | Treat cancellation or return dependent reports as potentially incomplete while the stream catches up. |
Do not infer that a Healthy stream makes every business metric current. For a planned stock correction, read the inventory stream and its observed time; for a retail PO queue, read POs; for finance, inspect Settlements where that adapter exists. Use Brand Health to interpret the resulting business signal after its underlying data is current.
Read the state and reason together
Healthy, Lagging, Problem, Setup, and NoActivity are distinct states. NoActivity means there is no run evidence, not that data is current. Setup can describe a newly connecting account. A failed connection makes its streams a Problem with ConnectionLost; resolve the account before interpreting stream-specific failures.
The reason field classifies what to investigate: PortalLoginRejected points to a seller-panel login, ConnectionLost to channel authorization, AccountAtRisk to marketplace standing, DataIssue to catalog data, and Drifting to stock disagreement. Transient, SyncFailing, and Overdue distinguish a retryable failure, another failed sync, or stale success without a more specific error. reason is null on a healthy result and can be null for a state derived from setup or missing activity. The API does not expose raw sync error text as the customer-facing reason.
A Transient failure can recover on a later run; use the next read to determine whether it did. PortalLoginRejected points to the portal credential rather than the marketplace API authorization. A ConnectionLost reason points to channel authorization. Keep those repair paths distinct when presenting a user action.
Understand which streams apply
Listings, orders, returns, and inventory are evaluated for connected accounts. POs appears only for a retail channel. Settlements appears only where a finance adapter can read that channel; an absent settlement stream is not a failed one. Listings use a six-hour expected cadence and settlements a daily one, with lagging/problem thresholds based on elapsed time since success. Orders and purchase orders are judged from failed runs. Returns failures signal delayed post-sale data. Inventory can be Drifting when channel-observed quantities disagree with Nasam's last push even if the sync itself did not fail.
For drift, inspect the inventory stream's drift counts and preview a drift resync before applying a stock correction. For a connection problem, read the connected account and use its reauthorization or portal-login workflow. For catalog data issues, inspect the review queue.
Sync Health measures capture and processing. Brand Health evaluates operational and business evidence. A missing or stale capture should not be interpreted as a healthy business result.