Financial Report

Retrieve the financial report's revenue, taxes, services, inventory, and expenses, without trending comparisons.

Financial Report

GET/api/v3/reports/financial

Required scope: reports:read

Requires the user's current report and invoice-list permissions and an accessible account. Like the web Financial Report, this is an account-wide report even for users without permission to view all invoices. There is no salesperson filter. Restricted credentials must explicitly include reports:read; inherit-all credentials follow live permissions.

Query parameters

Parameter	Default	Description
`date_from`	Today minus 30 days	Inclusive start date in `YYYY-MM-DD` format. Supply both dates or omit both.
`date_to`	Today	Inclusive end date, on or after `date_from`.
`category_id`	All categories	Optional account-owned inventory category UUID. Includes the selected category and its subcategories, matching the web report.

Dates use the application's calendar, with valid years 1000–9999. Invalid, incomplete, or reversed date ranges and invalid or unavailable categories return 422 invalid_query_parameter with the offending param. Categories belonging to another account receive the same error as unknown categories.

curl 'https://yourbusiness.salesbinder.com/api/v3/reports/financial?date_from=2026-10-01&date_to=2026-10-31' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Response

Returns one financial_report object, without pagination. filters echoes the effective dates and category UUID. category is either null or an object with id and name. currency and currency_decimal_places describe the account's reporting currency and precision (0–4). All monetary values are decimal strings. No currency conversion is performed.

days matches the web report's displayed elapsed day count: October 1–31 returns 30, while a same-day range returns 0. Both boundary dates are included in calculations.

Metrics

Field in `metrics`	Meaning
`gross_revenue`	Total invoiced including taxes; category sales including attributable line taxes when filtered.
`net_revenue`	Revenue excluding taxes.
`discounted_total`	Discounts, or discounts attributable to the selected category.
`profit_loss`	Combined inventory and services profit/loss.
`tax1_total`, `tax2_total`	Tax totals; top-level `tax1_name` and `tax2_name` provide configured labels.
`services_only_revenue`	Services revenue including shipping fees.
`services_only_cost`	Services costs including shipping costs.
`services_profit_loss`	Services revenue minus services costs.
`inventory_valuation`	Unsold inventory valuation based on unit costs.
`inventory_sales`	Inventory sales excluding taxes.
`cogs`	Cost of goods sold.
`purchased_inventory_valuation`	Newly purchased inventory value using the web report's purchase-order and unique-item calculations.
`inventory_profit_loss`	Inventory sales minus COGS and sold expenses.
`additional_expenses_valuation`	Additional inventory expenses valuation using the report end-date conditions.
`sold_expenses`	Additional expenses associated with inventory sold during the period.
`total_valuation`	Inventory valuation plus additional expenses valuation.

Service breakdown

service_categories contains {service_category_id, name, revenue, cost} objects. It includes a synthetic Shipping Fees row with a null ID, and uses Uncategorized when a service category has no name. service_category_totals contains revenue and cost totals for the breakdown.

Inventory valuation metadata

The top-level inventory_valuation object describes the amount in metrics.inventory_valuation:

{
  "source": "historical_snapshot",
  "as_of": "2026-10-30"
}

For an unfiltered past end date, the report uses the latest available historical snapshot on or before that date. If no snapshot exists, it falls back to current inventory. Category-filtered reports and current/future end dates use current inventory, returning source: "current_inventory" and the calculation's calendar date as as_of. Metadata is cached together with the value, using the web report's shared cache; it is not a guarantee of an uncached inventory read.

Calculation rules

Revenue uses issue dates of unpaid, partially paid, and paid-in-full invoices, not payment dates. Draft and cancelled invoices are excluded.
Purchased inventory uses eligible purchase-order issue dates and unique-item purchase dates, matching the web report.
Category filtering excludes shipping and service lines, which have no inventory category. Service metrics and breakdown totals are zero, and service_categories is empty.
An empty sales period returns zero sales metrics but may still have inventory valuation and expenses.
Values use the same rounding and cached calculations as the on-screen Financial Report.
Trend and comparison objects are never returned, and previous-period queries are not executed. There is no trends parameter.

Responses carry Cache-Control: no-store. This HTTP cache policy does not disable the shared server-side report cache.