Skip to main content

Promotions

The promotion operations read each of a brand's marketplace accounts with its promotions: the programmes a marketplace runs that the brand can join (deals, flash sales, campaigns) and the brand's own seller promotions (vouchers, coupons, discounts). They price listings at a promotion price and write to the marketplace: join, leave, create, edit and pause. Reads need promotions.read; writes need promotions.write.

Every request names one brand: brandId in the query of a read, in the body of a write. Nasam reads every account's promotions daily. An account's capturedAt says when, and reads says how each part of the last read went; a part that failed (readState: NoSignal) keeps the promotions Nasam read before.

Amazon promotions are read-only: they are listed with joinBlock: ReadOnlyMarketplace, and a write on one is a 403.

Find a promotion​

curl 'https://api.nasam.co/mm-api/v1/promotions?brandId=20&window=OpenAndUpcoming' \
-H 'accept: application/json' \
-H "Authorization: Bearer $NASAM_API_KEY"
QuestionOperation
What can the brand join or run now?List promotions: one entry per account, with its promotions and the seller promotion kinds it can create (creatable). window is OpenAndUpcoming by default, or Live or Ended30d.
What can be done with one promotion now?Get promotion: canJoin and joinBlock, editableFields, statusActions, isStockRequired and isLeaveReasonRequired.
Which listings are in it, or could be?List promotion listings with filter: Eligible reads the marketplace live; Enrolled, Rejected and NeedsCleanup read what Nasam stored.
What did promotions sell?List promotion results: units, revenue, each side's share of the discount and what the brand kept, over Riyadh days.

Each promotion has three deadlines, enroll, raisePrice and leave, each with at, its kind and isPassed. isDerived marks a deadline Nasam computed from the marketplace's rule rather than read.

Price a listing​

Each listing row carries its cap (the highest price the marketplace takes, and its options where it offers several), the referencePrice a deal must beat, blockers, and atCap: the money it makes at the cap. Before you choose a price, check promotion prices to get the same figures at the prices you propose. Nothing is written.

The figures are customerPrice, marketplaceSharePerUnit and sellerSharePerUnit of the discount, clearedPerUnit after fees and unit cost, and marginPct against targetMarginPct. A figure whose input Nasam does not hold is null, and the input is named in unknown. A loss or a below-target margin is flagged with isLoss and isBelowTarget, never refused.

Write with a preview​

Every write except a status change comes in two calls with the same body: a preview that sends nothing, then the write.

ChangePreview, then write
Join a promotion, or change a joined listing's pricePreview enroll, then enroll listings.
Take listings outPreview leave, then leave promotion. Send reason where the promotion has isLeaveReasonRequired.
Create a seller promotionPreview create, then create promotion, with a kind from the account's creatable. Pick its products with list listings for a seller promotion.
Change a seller promotionPreview edit, then edit promotion, changing only what editableFields lists.
Pause, resume or cancelSet promotion status with one of statusActions. It applies at once; a cancel cannot be undone.

The preview resolves each SKU to the marketplace's listing, reads the caps, checks stock, deadlines and the marketplace's own rules, and prices every listing. Each row says isWillApply, refusedReason or isUnchanged. When a step has isRiskOfLoss, such as a move that can lose a listing its place, the write needs isRiskAcknowledged: true.

The write plans again against the marketplace as it is then, sends only the listings that pass, and reads them back. Each row of results has a result: Accepted, Refused with the marketplace's reason, NotApplied, OtherPrice when the marketplace kept another price, Unconfirmed when it took the row and Nasam has not read it back yet, or NotSent. When every listing is refused the request is a 400, and a second write to a promotion while one is running is a 409. Send an Idempotency-Key on every write so a retry is safe.

Listings are keyed by sku with lane (Namshi's stock lane) and businessModel (noon's, such as core), both empty elsewhere. A listing row's rowKey joins the marketplace's key with the two.