Skip to main content

Inventory sources and demand planning

Nasam's shared stock pool has a source of truth when a brand has an active warehouse connection or an active D2C seller storefront. The source read requires brandId and returns type (WMS, D2C, or null) plus sourceName. An active WMS wins; an active D2C storefront is next. null means no source was resolved, so a newly connected channel cannot assume a shared pool anchored to one.

The source and the destination are different. A source tells Nasam where pool stock is anchored. A forecast destination can be the main warehouse, a marketplace fulfillment center, or a channel listing that holds its own stock. A product's destinations carry each location's currentUnits, inbound units, velocity, cover, need, and signal. The row's totalGapUnits covers channel destinations; the main warehouse's need stays on its destination to avoid double counting.

Decide where stock belongs​

  1. Read the brand's inventory source before treating a connected channel as part of the shared pool. WMS means an active warehouse connection anchors the pool; D2C means a seller storefront does. If type is null, investigate the intended source or use channel-specific inventory settings rather than assuming pooled stock.
  2. Read the account's inventory settings. inventoryScope tells you whether that account participates in the brand pool, tracks its own channel inventory, or is managed outside Nasam. A storefront's inventoryBranchId may select a particular branch.
  3. Read the forecast destinations for the product. Do not sum totalGapUnits and the main warehouse need: the latter describes the warehouse's procurement question and is already kept separate from channel transfer gaps.

This distinction matters when deciding whether to order stock, transfer stock to a fulfillment center, or correct a listing quantity. Those are different actions even when they concern the same SKU.

Read the forecast and missing inputs​

GET /inventory-planning returns inventoryForecast and pagination. Filter by brandIds, saleChannelIds, search, signals, and isOutOfStock. search matches SKU, barcode, English name, or Arabic name. Signals include NeedsAction, Excess, RestockWarehouse, Covered, and NoSignal. It defaults to page 1 and limit 25, with a maximum of 100. A saleChannelIds filter keeps a product row if any destination matches; it does not remove the other destinations from that row or change the row's roll-up.

isOutOfStock=true keeps the products out of stock somewhere a customer buys from: a listing at zero after a successful stock sync, or the main warehouse at zero while it feeds a self-shipped channel. It combines with signals; pair it with sortBy=Stock&sortOrder=ASC to read the emptiest first.

Signal counts use the forecast scope for a summary, and outOfStockCount counts the out-of-stock rows across every signal. Input gaps identify brands or SKUs relying on fallback lead time, shelf life, or holding inputs. A NoSignal destination includes a noSignalReason such as NeverClassified, NeverSold, InsufficientData, or NoActiveListing; it is not zero demand. Stock alerts provide a separate paginated operational view.

Read a product's destination rows before acting on its row-level signal. NeedsAction points to a channel shortfall, RestockWarehouse to the main warehouse, and Excess to more stock than the plan needs. A product row can carry several destinations with different signals; a channel filter retains the complete row for interpretation. NoSignal means the planner cannot make a demand recommendation for that destination, so inspect the reason and input gaps before treating the need as zero.

Read the forecast by parent​

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

Pass groupBy=parent to GET /inventory-planning to page through items: a parent is one item and a product with no parent is one item. limit and pagination.total count items. search, saleChannelIds and signals match variants, and a parent is on the page when any of its variants matches. inventoryForecast holds the matching variants of the page's items, contiguous per item, each with its variantLabel. parents carries each parent in page order with figures over all its active variants, matched or not: summed stock, gap and excess units, the earliest ideal ship date with the variant and destination it falls on, the worst signal, and needsActionVariantCount. Items sort by the parent's figure: the earliest date for IdealShipDate, the sums for Gap, Stock and Excess.

Sizes do not share stock, so the plan stays per variant. Days of stock, velocity, cover, the reorder point and each destination's signal are on the variant rows, and a parent's NeedsAction means at least one variant needs a transfer or order. Signal counts count SKUs either way.

Set planning inputs​

Read planning configuration with brandId to see declared values, defaults, and events. PUT the configuration is a full replacement of the brand's declared knobs: procurement lead time, target cover, fulfillment-center lead time, safety quantile, and seasonal multipliers. Read first and include every declaration you intend to preserve. Null or omitted numeric knobs use planner defaults; an omitted knob is not an unchanged knob. The update replans the brand and returns the resolved configuration. Compare that response with the previous read before assuming a seasonal or safety setting survived.

Product forecast inputs​

A product's forecast inputs are its declared weight, dimensions, shelf life, and holding limit. They are declared in the Nasam app, where a product-info file runs as a tracked import under Data → Imports.

Product inputs and brand planning configuration serve different levels. Set a missing product shelf life or holding limit on the product, then re-read its forecast after planning catches up. Use the input-gaps read to find where fallback values still stand in for declared values. Do not use a listing price or stock update to correct a forecast input.

Diagnose drift before a write​

The three correction pairs answer different questions:

If you need to…PreviewApply
Push the existing pool to channel listingsReconcile previewReconcile
Anchor the pool to its source truth, then push itReanchor previewReanchor
Re-push only channels whose observed stock differs from the last pushDrift previewDrift resync

Every request supplies brandId. Reanchor also accepts shouldReadFromSource: when true, Nasam reads the live storefront or WMS instead of its stored mirror and fails the request if that live read fails. Previews write nothing. A drift preview includes per-channel currentQuantity, newQuantity, and willRaise; a raised channel deserves an order check before applying, because an unrecorded sale could make the lower observed number correct. These writes change quantities, not listing status. Re-read the source, forecast, and Sync Health after an apply.

Correction runbook​

  1. Identify whether the pool is wrong or only its channel copies are wrong. If the pool is trusted, preview reconcile. If a WMS or D2C source is authoritative and the pool must be refreshed from it, preview reanchor. If the issue is a channel read-back that differs from Nasam's last push, preview drift resync.
  2. Review the preview's affected products and channel quantities. For a drift row with willRaise: true, check recent orders on that channel before raising available quantity. A lower channel value can reflect a sale Nasam has not captured yet.
  3. Apply only the matching operation after that review. For reanchor with shouldReadFromSource: true, a live source read failure stops the write; inspect the connection instead of falling back silently to the stored mirror.
  4. Re-read stock and sync state. A successful apply means the correction request ran; confirm the resulting pool and destination values and inspect channel processing before reporting the marketplace quantity as current.

Read the warehouse source​

A brand connects its warehouse (WMS) in the Nasam app. Through the API, list the brand's warehouses to see the connected account and its status, and read stock readings for the last quantities Nasam received from it. Only one warehouse account is active for a brand at a time.

Stock readings are the last WMS quantities Nasam received, not a live read. If a correction depends on the warehouse's current values, set shouldReadFromSource: true on both the reanchor preview and the matching apply. Read the inventory source to confirm whether WMS is authoritative for the brand before you rely on warehouse quantities.