Skip to main content

Catalog, listing review, and pricing

A Nasam product is the brand's SKU. A listing is that product's presence on a connected sale-channel account. One product can therefore have several channel listings, each with its own status, price, and stock. Products and listings mirror what the connected marketplaces report: they arrive through channel sync and catalog review, and a bulk update changes existing listings on the marketplace rather than creating new ones.

Pick the catalog action​

SituationUseCompletion check
You need the brand's products and channel presenceProduct directoryInspect each product's listings, then read a listing in detail if needed.
A newly connected account has unmapped channel itemsReview backlog, then account reviewResolve the review item, then re-read the account's review and mapped counts.
You need to push price, promotion dates, or inventory to existing listingsBulk listing updateCheck row errors, then the listing and Sync Health.

Read the catalog​

GET /products returns products, categories, filterCounts, and pagination. Each product includes its listings. A listing's embedded saleChannelAccount in this catalog response contains only fulfillmentModel and the channel's id, name, and region; use connected accounts when you need connection status or inventory settings.

Use brandIds to narrow to brands your key can access. ids narrows to known product IDs; excludedSaleChannelIds, categories, productTiers, sku, name, and listingFilter refine the catalog. listingFilter accepts values such as Active, BuyBoxLost, OutOfStock, and Suppressed. filterCounts counts what the other filters match, so it stays the same whichever listingFilter you pass: all is the number of distinct products, and each other count tallies their listings, so a product listed on several channels adds more than once. sortBy accepts TotalRevenue, TotalUnitsSold, TotalAvailableQuantity, or UpdatedAt; sortOrder is ASC or DESC. This read defaults to page 1, limit 10, sorted by revenue descending, and caps the limit at 100. Categories lists category names for a brand selection. Listing detail is the focused read for one listing.

Pass statusUnit=product to count and filter by product instead. Each product then has one status, read from its listings on the channels excludedSaleChannelIds leaves: Active when it is live (active, or sold out and still up) on every one of those marketplaces it is listed on, PartlyActive when it is live on some and not others, otherwise its most pressing state (Suppressed, then AtRisk, then InActive, and Archived only when every listing is archived). A product on none of those marketplaces but on the brand's own store (Salla, Zid), in any state but deleted, is NotListed. When only own stores are left, each product takes its status on the store. The status counts add up to all, the products with a status; buyBoxLost, outOfStock (sold-out listings included) and discounted count the products with a listing like that, and notOnStore the products on one of those marketplaces that are not active on the brand's own store (a range sold only on marketplaces), all outside that sum. listingFilter then keeps the products whose status you pass and accepts PartlyActive, NotListed and NotOnStore, which answer 400 without statusUnit=product. When it passes a status, buyBoxLost, outOfStock, discounted and notOnStore count only the products in that status, so you can see how many of your inactive products are out of stock; the status counts stay the same. Add hasChannelPresence=true so products holds exactly the products all counts.

Listing detail also returns product.brandId and the listing's content. A standard is something the listing's channel recommends for its category but does not enforce. standardsCounted is how many of the channel's standards Nasam could judge on the listing's stored content (suggestions excluded), standardsMet how many of those it meets, and openFindings the wrong or unclear claims and channel-reported problems still open from the last nightly check; a standard not met counts in the standards, not in openFindings. Nasam checks content on Amazon, noon and Trendyol; a listing on any other channel reads zero for all three. standardsCounted is zero too where none of the channel's standards for the category can be judged yet, so compare standardsMet with standardsCounted, never with a fixed number.

curl --get 'https://api.nasam.co/mm-api/v1/products' \
--data-urlencode 'brandIds=20' \
--data-urlencode 'listingFilter=OutOfStock' \
--data-urlencode 'page=1' \
--data-urlencode 'limit=25' \
-H "Authorization: Bearer $NASAM_API_KEY"

Read by parent​

A parent is one design a brand sells in several sizes or colours; each size or colour is a variant, a product with its own SKU. A product that is a variant carries the parent's opaque key in parentKey; a product with no parent has parentKey: null. The same key appears on every grouped read across the API, so rows from different operations can be matched to one parent.

Pass groupBy=parent to GET /products to page through items instead of products. A parent is one item and a product with no parent is one item; limit and pagination.total count items, not variants. Every filter matches variants, and a parent is on the page when any of its variants matches. products holds the matching variants of the page's items, contiguous per item, each with variantLabel (what sets it apart, such as Red / M) and variantLabelAR, both null when nothing is left past the shared name. parents carries each parent in page order with its figures over all its variants: summed stock, units and revenue, its price range, and outOfStockVariants. To read every variant of one parent, request groupBy=parent&ids={productIds}&limit=1 with that parent's productIds.

A parent groups variants for reading. Each variant keeps its own listings, stock, price and status, and every write, such as a bulk update, still names one SKU.

curl --get 'https://api.nasam.co/mm-api/v1/products' \
--data-urlencode 'brandIds=20' \
--data-urlencode 'groupBy=parent' \
--data-urlencode 'limit=10' \
-H "Authorization: Bearer $NASAM_API_KEY"

Resolve imported listings​

After a channel account connects, Nasam matches channel items to brand products. The backlog identifies accounts with unresolved items; the account review groups them into NeedsBrand, PossibleMatch, New, and CannotMap. It also reports mapped and attention counts, onboarding status, and last/next sync times.

For a review decision, send its itemIds as strings from the review response. Choose the action by what you have verified:

Review findingActionWhy
The suggested product is the same physical itemConfirmAccept the suggested match.
The item belongs to an existing product, but the suggestion is wrong or absentLink with that productIdKeep one product across its channel listings.
The item belongs to another brand sharing the marketplace accountAssign brand with targetBrandIdAttribute the item to its business owner before mapping it.
The item represents a new brand productAdd newCreate a Nasam product from the channel item.
A PossibleMatch suggestion is incorrect and the item is its own productNot a matchReject the suggestion and create a separate product so the next sync does not suggest the same wrong match again.

Dismiss and undo-dismiss manage the review queue. Recheck and retry matching start another review or match pass. An action response is not a substitute for reading the queue again: the account can have other pending items and an onboarding failure reason.

SKU or barcode can produce a confident match; Trendyol stock code is compared with SKU. A unique normalized name with the exact price can appear as a possible match that still needs a decision. Preserve the brand's exact SKU, including case and whitespace, and give each variant its own SKU. A similar title alone is not a safe link key.

Review a connection from start to ready​

  1. Read the connected account to get the account ID. The channel definition ID is a different value and cannot replace it in the review path.
  2. Read the backlog to find accounts with pending items, then open that account's review. NeedsBrand needs ownership, PossibleMatch needs a product decision, New may need product creation, and CannotMap needs its problem inspected before retrying.
  3. Submit an action using only item IDs returned by that account review. Do not rebuild item IDs from SKU or title.
  4. Read the review again. Compare attentionCount, mappedCount, status, failureReason, and lastSyncedAt. If the account is still Matching or Failed, do not claim that the catalog is ready because one item disappeared from the queue.

Update existing listings​

JSON bulk update accepts an updates array. Each row identifies a SKU or barcode, supplies saleChannelIds, and can carry listPrice, salePrice, sale dates, or inventory. A price change reaches the channel as the listing's whole price (list price, sale price and sale dates together). Omitting salePrice keeps a running sale and its dates, salePrice: null ends it, and a new salePrice sent without dates runs with no end date. The service validates the whole batch and returns success, totalItems, validItems, and possible errors. A successful validation schedules a price push when any row carries a price and a stock push when any row carries inventory; it does not mean every marketplace has already applied them. Check the affected listings and Sync Health after processing.

Before sending a bulk update, read the product and confirm that each requested channel already has the intended listing. Treat SKU or barcode as an exact identity check, especially for variants. After submission, inspect errors even when the HTTP request succeeds. Then wait for processing and compare the resulting listing's price or quantity with the requested change. A stale or failed sync belongs in the sync workflow; do not keep replaying a bulk write merely because the initial response was accepted.

Product names, SKUs, barcodes, and images come from the marketplace; change them on the channel and the next sync carries them into Nasam. Product forecast inputs are declared in the Nasam app (forecast inputs); they are not a listing price upload.