Reports API — Sales, Store, and Company Analytics

Credith exposes four analytical report endpoints that cover different scopes of the business: product-level performance across a company, a day-by-day store gain series over a custom date range, a monthly revenue and staffing summary for a single store, and aggregated financials rolled up to the company level. All four operate against the cd schema using raw PostgreSQL queries with CTEs, and all return pre-computed grossGain and netGain figures calculated from sell_price - buy_price margins.

All four report endpoints are restricted by role. GET /api/reports/products and GET /api/reports/companies require the OWNER role. GET /api/reports/stores and GET /api/reports/stores/range accept either OWNER or ADMIN. The API-level roleMiddleware enforces this — requests from EMPLOYEE-role users are rejected with 403. Ensure the JWT in the Authorization header belongs to a user with the appropriate role.

`GET /api/reports/products`

Returns product performance data for a company, broken down by product and store. For each product the response includes total quantity sold, current in-stock units, gross gain (sell price margin × qty), and net gain (line total margin × qty) — both for the company as a whole and per individual store. When no month/year is provided the report covers all historical sales. When a period is specified, only bills created within that calendar month are included. Query parameters

companyId

string (UUID)

required

Limits the report to products sold by or stocked in stores belonging to this company.

storeId

string (UUID)

Optional. Narrows both the sales and inventory queries to a single store within the company.

month

string | integer

Optional. Accepts either a numeric month (1–12) alongside year, or a combined YYYY-MM string (e.g. "2026-05"). When omitted together with year, the report covers all historical data.

year

integer

The four-digit calendar year. Required when month is sent as a plain integer.

limit

integer

default:"10"

Maximum number of products to return per page. Capped at 100.

offset

integer

default:"0"

Number of products to skip (for pagination).

Example

curl -X GET "https://your-domain.com/api/reports/products?companyId=cc001122-9ae8-4597-b95e-9889028f0001&month=2026-05&limit=10&offset=0" \
  -H "Authorization: Bearer <token>"

Response fields

period

object

Describes the date range applied to the query.

Show period fields

period.type

string

"historical" when no date filter was applied; "month" when a specific month was requested.

period.year

integer

Calendar year (only present when type = "month").

period.month

integer

Calendar month 1–12 (only present when type = "month").

period.startDate

string (date)

Inclusive start of the period window.

period.endDate

string (date)

Exclusive end of the period window.

products

array

Paginated list of product performance objects.

Show product fields

productId

string (UUID)

UUID of the product.

name

string

Product name, ordered alphabetically.

quantitySold

integer

Total units sold across all matching stores in the period.

inStock

integer

Total units currently in stock across all matching stores.

grossGain

number

Company-level gross gain: SUM((sellPrice - buyPrice) × quantity).

netGain

number

Company-level net gain: SUM(lineTotal - buyPrice × quantity).

stores

array

Per-store breakdown. Each entry has storeId, address, quantitySold, inStock, grossGain, and netGain for this product in that store.

Error responses

Status	Cause
`400`	`companyId` missing, invalid `month`/`year` combination

`GET /api/reports/stores`

Returns the monthly revenue summary and employee roster for a single store. If no month/year is specified, the current calendar month is used by default. Requires ADMIN or OWNER role. Query parameters

storeId

string (UUID)

required

UUID of the store to report on.

month

string | integer

Optional. Numeric month (1–12) with year, or YYYY-MM string. Defaults to the current month.

year

integer

Required when month is a plain integer.

Example

curl -X GET "https://your-domain.com/api/reports/stores?storeId=d55555e5-9ae8-4597-b95e-9889028f3333" \
  -H "Authorization: Bearer <token>"

Response fields

store

object

Monthly performance snapshot for the requested store.

Show store fields

storeId

string (UUID)

UUID of the store.

address

integer

Store address number (integer, e.g. 101).

isOperating

boolean

Whether is_active is true for this store.

monthlyGrossGain

number

Gross gain for the period: SUM((sellPrice - buyPrice) × quantity).

monthlyNetGain

number

Net gain for the period: SUM(lineTotal - buyPrice × quantity).

employees

array

All users assigned to this store (not scoped to the period).

Show employee fields

userId

string (UUID)

Employee UUID.

fullName

string

Concatenated first and last names.

string

Employee email address.

isActive

boolean

Whether the employee account is active.

Error responses

Status	Cause
`400`	`storeId` missing or invalid date parameters
`404`	No store found for the given `storeId`

`GET /api/reports/stores/range`

Returns a day-by-day series of gross and net gain for a store between two calendar dates. Each entry in data corresponds to a single calendar day; days with no sales return grossGain: 0, netGain: 0. Requires ADMIN or OWNER role. Query parameters

storeId

string (UUID)

required

UUID of the store.

startDate

string (date)

required

Inclusive start date in YYYY-MM-DD format.

endDate

string (date)

required

Inclusive end date in YYYY-MM-DD format.

Response

{
  "data": [
    { "date": "2026-05-01", "grossGain": 1200.00, "netGain": 1140.00 },
    { "date": "2026-05-02", "grossGain": 0, "netGain": 0 },
    { "date": "2026-05-03", "grossGain": 3450.00, "netGain": 3277.50 }
  ]
}

Error responses

Status	Cause
`400`	`storeId`, `startDate`, or `endDate` missing; dates not in `YYYY-MM-DD` format

`GET /api/reports/companies`

Returns aggregated monthly revenue for every active store within a company. Defaults to the current calendar month if no period is specified. Requires OWNER role. Query parameters

companyId

string (UUID)

required

UUID of the company to report on.

month

string | integer

Optional. Numeric month (1–12) with year, or YYYY-MM string. Defaults to the current month.

year

integer

Required when month is a plain integer.

Example

curl -X GET "https://your-domain.com/api/reports/companies?companyId=cc001122-9ae8-4597-b95e-9889028f0001" \
  -H "Authorization: Bearer <token>"

Response fields

company

object

Aggregated company report.

Show company fields

companyId

string (UUID)

UUID of the company.

name

string

Company name.

rtn

string

Company tax ID (RTN).

string

Company contact email.

totalMonthlyGrossGain

number

Sum of monthlyGrossGain across all active stores.

totalMonthlyNetGain

number

Sum of monthlyNetGain across all active stores.

stores

array

Per-store breakdown. Only stores where is_active = true are included.

Show store summary fields

storeId

string (UUID)

UUID of the store.

address

integer

Store address number (integer, e.g. 101).

isOperating

boolean

Always true for this endpoint (only active stores are included).

monthlyGrossGain

number

Store’s gross gain for the period.

monthlyNetGain

number

Store’s net gain for the period.

Error responses

Status	Cause
`400`	`companyId` missing or invalid date parameters
`404`	No company found for the given `companyId`

Overview

Users & Access

Organization

Catalog

Billing & Payments

Analytics

Reports API — Sales, Store, and Company Analytics

`GET /api/reports/products`

`GET /api/reports/stores`

`GET /api/reports/stores/range`

`GET /api/reports/companies`

Build docs developers (and LLMs) love

Overview

Users & Access

Organization

Catalog

Billing & Payments

Analytics

Documentation Index

​GET /api/reports/products

​GET /api/reports/stores

​GET /api/reports/stores/range

​GET /api/reports/companies

Build docs developers (and LLMs) love

`GET /api/reports/products`

`GET /api/reports/stores`

`GET /api/reports/stores/range`

`GET /api/reports/companies`