Skip to main content

Get Sales Order Financials (Proforma)

GET 
/api/sales-orders/:salesOrder/financials

Recalculates and returns proforma (on-the-fly) line-level financials for a single sales order. The endpoint runs the API::calculate for the order before responding, so figures always reflect current FIFO cost assignments — including the bundle cost-based revenue correction.

Required scope: orders:read

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

Authentication: Requires Bearer token.

Response (wrapped in {data}):

  • id: Sales order ID
  • is_tax_included, currency (code cached at time of sale), currency_rate
  • sales_order_lines[]: per-line proforma P&L:
    • product: {id, sku, name} (present when the line is a product line)
    • description, quantity, price (per-unit amount in tenant currency), tax_allocation, tax_rate_id
    • revenue: recognized revenue for the line (after any bundle cost-based correction)
    • revenue_allocation_basis: "document" (revenue follows the order document) or "cost_corrected" (bundle-group revenue re-allocated in proportion to actual COGS so no component shows a phantom line-level loss)
    • document_revenue: pre-correction revenue computed from the order document (quantity × amount − included tax); equals revenue unless revenue_allocation_basis is cost_corrected
    • bundle_id: parent bundle product ID when the line was expanded from a bundle (null otherwise)
    • bundle_proration_basis: how the bundle's price was prorated across components at order entry — "cost", "price", or "quantity" (null for non-bundle or legacy lines)
    • bundle: {id, sku, name} (present when bundle_id is set)
    • revenue_allocated, credits, discount, total_revenue
    • cogs, cost_allocated, cogs_returned, total_cost
    • profit, profit_margin
    • per_unit: {revenue, revenue_allocated, credits, discount, total_revenue, cogs, cost_allocated, cogs_returned, total_cost, profit}
    • cost_breakdown: cost category → amount map
    • cost_breakdown_layers[]: FIFO layer-level cost detail (layer_kind, fifo_layer_id, fifo_layer_date, quantity, source_type, source_label, source_id, breakdown, total, unit_cost)
    • fifo_layers[]: {id, name, quantity, unit_cost, total_cost, revaluation_delta, restated_unit_cost, restated_total_cost, layer_date}

Returns-pending COGS: each line splits returned cost into cogs_returned_realized (cost reversed by physical return receipts) and cogs_returned_pending (imputed expected cost of refunded units still awaiting return), with a return_pending boolean; the same split is available under per_unit.*. The order-level has_return_pending flag is true when any line has a return still in flight. A refunded-but-un-received order nets to ~0 while return_pending is true; closing or canceling the RMA without receiving the goods clears the pending imputation and reveals the real loss.

Each line includes indirect_cost_allocated (the line's revenue-weighted share of cost-entry / overhead allocations), contribution_profit (profit minus that share) and contribution_margin (a fraction of revenue), plus their per_unit variants. These are standalone — profit, total_cost and profit_margin are unchanged by them.

Cost restated after shipping: a supplier invoice correcting the purchase price, or landed cost added once the goods had already shipped, restates the FIFO layer the sale drew from. cogs deliberately stays on the cost booked when the order shipped, and the restatement is reported separately so it is never double-counted: cogs_revaluation is the line-total restatement (positive when the goods turned out to cost more), with cogs_restated, total_cost_restated and profit_restated giving the same line valued at today's costs, and per_unit.cogs_revaluation the per-unit figure. Each entry in fifo_layers[] carries the same split: unit_cost/total_cost as booked, and revaluation_delta/restated_unit_cost/restated_total_cost after the restatement. cogs_revaluation is 0 when nothing has been restated.

Request​

Responses​

OK

Response Headers
    Content-Type