sales_velocity

get sales velocity table totals

The sales velocity table's totals over every filtered row, as one entry per period: units sold and revenue, forecast demand and its revenue, effective demand (forecast adjusted for stockouts), the same period a year earlier, and the velocity rate the forecast used.

It takes the same filter_args and search as get_sales_velocity_table, so the totals match the rows a caller is looking at. start_date and end_date set the window, include_last_year adds the prior-year figures and aggregation_mode sets how periods are summed.

first_forecast_date is set only on the period holding the day forecasting first ran for this organisation, and is null on every other. Missing forecasts remain null rather than zero. Historical partial forecasts retain their recorded amount and expose forecast_coverage on commitment-scoped PostgreSQL reads.

Scope: sales:read.

get/api/v1/sales/velocity/table/totals

Request

  • Base URL: https://api.app.tightly.io
  • URL: https://api.app.tightly.io/api/v1/sales/velocity/table/totals
  • Auth: HTTP bearer

Query parameters

filter_argsstring
Example:[{"key":"location_id","operation":"in","value":["60904046659","63148523587"]}]

JSON array of filter conditions. Same filter keys as the sales velocity table: location_id, sales_velocity_30_days, modified_status, variant_id, product_id, supplier_id, event_id, shopify_tags, sales_channel_id, season_id. An unknown season_id is refused with a 400 that names it, and an empty season_id list with a 400 too.

searchstring

Search keyword to filter by product or variant title

start_datestring date
Example:2024-01-01

Start date for the sales velocity analysis period

end_datestring date
Example:2024-12-31

End date for the sales velocity analysis period. Must be provided together with start_date.

include_last_yearboolean

When true, includes last year comparison data in the totals

aggregation_mode'daily' | 'weekly' | 'monthly'

Time bucket for period columns. Auto-selected based on date range when omitted: daily (≤14 days), weekly (≤90 days), monthly (otherwise).

Headers

Tightly-Versionstring
Example:2026-11

The date train to answer on. One train exists today, 2026-11, the one this reference describes and the one every key is minted on, so the call answers on it with or without this header. Send it anyway, so a client built now names its train from the start.

Response

The sales velocity totals

dataobject

One entry per time bucket in totals, the data_source that served them (ch or pg), and the scope the denominators were counted over, or the reason there is none, which is not the same as a scope of nothing. On a weekly chart each bucket also names its week's key in week_grids, which converts that Monday-keyed week to the plan's 4-5-4 Sunday week: the plan week it falls inside, that week's fiscal year and number, and how the seven days split between it and the next (6 and 1). That split describes the keyed week itself, not the bucket: a bucket clipped by start_date or end_date covers only part of its week, and min_date / max_date remain the bucket's own bounds. Daily and monthly buckets carry week_grid: null and week_grids is empty, those buckets are not weeks.

messageobject

severity, service and desc.

Changes

No recorded changes to this operation across all 1 revision of this API.