Skip to main content

Get Supplier Leaderboard

GET 
/api/reporting/suppliers/leaderboard

Leaderboard rows only — a lightweight endpoint for table page/sort changes on the macro supplier view, without recomputing KPIs, movers, or the heatmap. Rows are computed in-memory from snapshots, then filtered, sorted and sliced; low-volume suppliers are flagged via is_low_volume.

Required scope: reports:read

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Server-paginated (PRD edge case 15: 500+ suppliers) — returns the standard Laravel pagination envelope (data, current_page, last_page, per_page, total, etc.).

Authentication: Requires Bearer token (scope: reports)

Required parameters:

  • period_mode: yoy | qoq | mom | custom

When period_mode=custom, date_from and date_to (YYYY-MM-DD or m/d/Y) are both required.

Optional:

  • growth_basis: spend | sales | profit | margin (default: sales)
  • min_volume: numeric — low-volume threshold (default: 1000)
  • include_archived: boolean (default: false)
  • sort: sort key, prefix - for DESC. Allowed: name, purchase_volume, sales_volume, units_purchased, units_sold, profit, margin_pct, growth_pct, active_po_count (default: -purchase_volume)
  • page: page number (default: 1)
  • per_page: rows per page (default: 10)
  • filter[search]: substring match on supplier name
  • filter[volume]: above | low — volume band filter

Request​

Responses​

OK

Response Headers
    Content-Type