Skip to main content

Get Staff Margins for Products (View as buyer only)

GET 
/api/portal/staff/margins/products

Staff-only margin overlay for a "View as buyer" session. Answers 403 (reason: staff_margins_unavailable) to every caller except a staff view token whose staff user holds portal.manage AND financials.index (checked live on each request) — a buyer login never receives cost data. Not embedded in the catalog payload: the portal fetches it only while "Show margins" is on. Sent with Cache-Control: no-store.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

Per product, one entry per price level the catalog shows: price (the buyer's price) step-<min_subtotal> for each order-value ladder step, and preorder-<min_subtotal> for each pre-order step of the product's catalog (a net-priced item keeps its price on every step). Margin = (price − cost) / price. average = FIFO average cost of stock on hand (what SKU books as COGS); replacement = the default supplier's price. A basis with no cost is null (never 0). currency_mismatch is true when the account's price list is not in the base currency (no margins then). When the tenant sets a replacement cost adjustment (Portal settings → Staff margin overlay, e.g. −15 "at special" for a merchant that only buys at the supplier's specials), replacement is the supplier price moved by it, bases.replacement names it, and replacement_adjustment = {percent, label} (null = none). A product with no FIFO cost (never stocked) shows the adjusted replacement figure as its headline.

Request​

Responses​

OK

Response Headers
    Content-Type
    Cache-Control