Skip to main content

Get Supplier Margin Ladder

GET 
/api/reporting/suppliers/:supplier/margin-ladder

Plan-versus-actual margin for one supplier over the resolved period.

Authentication: Requires Bearer token (scope: reports)

Two halves, deliberately kept apart because they are not the same measurement:

list — the plan, from price lists only. The gap between the retail price on the chosen sell tier and this supplier's cost on the chosen cost tier, across the products they supply. Two reads:

  • catalogue — a straight average across every priced product (each SKU counts once)
  • units_weighted — weighted by units actually sold in the period, so the busy SKUs dominate

The two diverge whenever sales concentrate in a subset of the catalogue; units_weighted is the fairer thing to compare the actuals against. avg_sell_price / avg_cost_price / weighted_sell_price / weighted_cost_price expose the inputs, and coverage reports how many of the supplier's products carry both a price and a cost (available is false when none do).

actual — what really happened, from shipped sales lines in the period. Three rungs, each subtracting one more layer of cost from the same revenue:

  • gross — revenue less cost of goods sold, net of returned goods
  • net — gross less direct costs (shipping, fees, packaging)
  • contribution — net less allocated indirect costs

gross_vs_list_pts, gross_to_net_pts and net_to_contribution_pts are the step sizes in percentage points (negative = margin lost at that step). coverage reports how many sold lines had a recorded cost of goods, which is the honesty check on the whole actual half.

Margin conventions. Every margin object restates one gap five ways: margin_pct ((sell - cost) / sell), off_retail_pct (the same number read as a discount off the retail list price), cost_ratio_pct (cost / sell), markup_pct ((sell - cost) / cost), multiplier (sell / cost) and amount (the money). off_retail_pct is null on net and contribution — once shipping and overhead are subtracted the result is no longer a discount off a list price, so publishing it there would be wrong. Every field is null when either side is missing or revenue is zero.

Only the actual half can carry direct and indirect costs; list prices have none, so the plan half stops at gross by design.

Required: period_mode. When period_mode=custom, date_from and date_to are both required (YYYY-MM-DD or MM/DD/YYYY) and date_to must be on or after date_from. sell_tier_id / cost_tier_id default to the account's default retail and supplier tiers; tiers and selected_tiers come back on every response so a caller can render the pickers without a second request.

Request​

Responses​

OK

Response Headers
    Content-Type