StateSet API Docs

StateSet exposes two different reporting surfaces, and picking the wrong one is the usual reason a number looks wrong.

	Analytics	Reports
Path	`GET /api/v1/analytics/*`	`POST /api/v1/reports/*`
Answers	”What is happening right now?"	"What happened over this period?”
Shape	Read-only, no body, current-state metrics	Takes an explicit date window and the records to run over
Use for	Dashboards, alerting, live tiles	Month-end close, COGS, channel attribution, aging

Analytics are computed from live data and are not point-in-time stable — the same call an hour later returns different numbers. Anything that has to reconcile, or be defensible to a finance team, belongs in Reports, which take an explicit from/to window.

Analytics

Endpoint	Returns
`GET /api/v1/analytics/dashboard`	The combined tile set behind the console dashboard
`GET /api/v1/analytics/sales`	Order counts and revenue for today, this week, this month, and all time
`GET /api/v1/analytics/sales/trends`	A daily series — takes `days` and `status`
`GET /api/v1/analytics/inventory`	Stock position, with a configurable `low_stock_threshold`
`GET /api/v1/analytics/carts`	Open, converted and abandoned cart counts
`GET /api/v1/analytics/shipments`	Shipment volume and status mix

curl "https://api.stateset.com/api/v1/analytics/sales" \
  --header "Authorization: Bearer $STATESET_API_KEY"

Response

{
  "success": true,
  "data": {
    "total_orders": 48213,
    "total_revenue": "3914022.55",
    "average_order_value": "81.18",
    "orders_today": 194,
    "revenue_today": "15748.30",
    "orders_this_week": 1322,
    "revenue_this_week": "107934.12",
    "orders_this_month": 5701,
    "revenue_this_month": "462880.41"
  }
}

Money is returned as a decimal string, not a float, so that cents survive JSON round-tripping. Parse it with a decimal type, not parseFloat. The trend endpoint is the one to build a chart on — days sets the window and status narrows which orders count:

curl "https://api.stateset.com/api/v1/analytics/sales/trends?days=30&status=fulfilled" \
  --header "Authorization: Bearer $STATESET_API_KEY"

Reports

Reports are POST because they take a window and the record set to run over, rather than reading whatever is current.

Endpoint	Answers
`POST /api/v1/reports/sales-by-channel`	Which channel produced which revenue over a window
`POST /api/v1/reports/transaction-cogs`	Cost of goods against each transaction
`POST /api/v1/reports/inventory-aging`	How long stock has been sitting, bucketed
`POST /api/v1/reports/consumption`	Material consumption across the window
`POST /api/v1/reports/close-the-books`	The period close summary

Every report takes an inclusive from and to as YYYY-MM-DD:

curl --request POST "https://api.stateset.com/api/v1/reports/sales-by-channel" \
  --header "Authorization: Bearer $STATESET_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "2026-07-01",
    "to": "2026-07-31",
    "records": []
  }'

from and to are inclusive on both ends. A month-by-month series built with 2026-07-01→2026-08-01 counts the first of August twice — once in July’s report and once in August’s. End the window on the last day of the month.

Scheduling an export

There is no server-side scheduler for reports: run them on your own schedule and put the result where it needs to go. A cron job calling the endpoint is the whole pattern.

// Monthly close: run on the 1st, for the month that just ended.
import { StatesetClient } from "stateset-node";

const client = new StatesetClient({ apiKey: process.env.STATESET_API_KEY });

const now = new Date();
const first = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 1, 1));
const last = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 0));
const day = (d) => d.toISOString().slice(0, 10);

const report = await client.request("POST", "/api/v1/reports/close-the-books", {
  from: day(first),
  to: day(last),
  records: [],
});

// Hand it to wherever your finance team actually reads it.
await fetch(process.env.FINANCE_WEBHOOK_URL, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(report),
});

Run the close job a day or two after month end rather than at midnight on the 1st. Late-settling payments and next-day fulfilment events land after the window closes, and a report run too early will disagree with the one anyone runs later.

Next steps

Analytics endpoints

Full request and response reference for every analytics endpoint.

Webhooks

React to events as they happen instead of polling an analytics endpoint.

Order operations

The workflows that produce the numbers these reports read.

COGS quickstart

How cost of goods is recorded, which is what transaction-cogs reports on.

Last modified on August 29, 2026

Get started

Platform

Using the APIs

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce Engine

StateSet iCommerce EDI Engine

StateSet Mail

StateSet iCommerce Voice Engine

StateSet iCommerce NSR Engine

AI Agents

StateSet Agents

StateSet iCommerce Sandbox Engine

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Apps & Consoles

Tools

Reporting

Analytics

Reports

Scheduling an export

Next steps

Analytics endpoints

Webhooks

Order operations

COGS quickstart

​Analytics

​Reports

​Scheduling an export

​Next steps

Analytics endpoints

Webhooks

Order operations

COGS quickstart

Analytics

Reports

Scheduling an export

Next steps