Shipping margin report (per-package classification)
reports:readReturns a synchronous per-package shipping margin report classifying
every shipped label by profit, breakeven, loss, or
refund_overpay. Sources from reporting.vw_shipping_margin which is
backed by the persisted shipping_margin_* columns on
fulfillment.packages (computed once at label purchase / void).
Layer 1 entity_id is enforced; sister-entity rows are unreachable.
Three blocks returned:
summary— per-status totals + counts + grand totals for the windowby_carrier[]— top 50 carrier+status rollup ordered by worst marginpackages[]— per-package detail (capped at 500) with order context
Industry parallel: NetSuite Shipping Performance Report, Shopify
Shipping Margin analytics. Distinct from the async report job cluster
(POST /v1/reports); this endpoint returns inline data.
Authorizations
API key issued per entity via Settings > Developers > API Keys.
Each key carries scopes (e.g. orders:read, products:write).
Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity
via Settings > Developers > API Keys.
Query Parameters
Lookback window in days (clamped to 1..365)
1 <= x <= 365Filter to a single margin status
profit, breakeven, loss, refund_overpay Free-text carrier name (ILIKE match, e.g. UPS, FedEx)
60Sort order for the packages[] block
worst_loss, shipped_at_desc, margin_pct_asc 
