Pull sales and stock reports
Read sales totals, per-store and per-item sales for a date range, and current stock for every item, paging through long results.
The report endpoints return figures iotoms has already added up, so you do not have to fetch every sale and total it yourself. This guide pulls a sales summary for a date range, splits it by store and by item, and then exports current stock for every item.
At the end you will have revenue, discount and return totals for a period, a per-store and per-item breakdown, and a full stock list, which is enough to feed a BI tool or a finance export.
Before you start you need a token and the merchant's tenant code. See Authentication.
How dates and paging work in reports
from and to are dates (YYYY-MM-DD). Both are inclusive and match each sale's business
date. Left out, both default to today. A from later than to returns 400 with
INVALID_DATE_RANGE. Sales report figures leave out voided sales. Paged reports return rows
in data.content and paging details in data.page (number, size, totalElements and
totalPages). Pages start at 0 and size can be up to 100.
Step 1 — Get the sales summary
One call gives the headline numbers for the period.
curl 'https://beta.iotoms.com/api/v1/reports/sales/summary?from=2026-10-01&to=2026-10-18&expand=summary&page=0&size=31' \
-H 'X-TenantID: <tenant-code>' \
-H 'Authorization: Bearer <token>'From data:
totalRevenue,totalTransactionsandaverageOrderValue.totalDiscountandtotalReturns.netRevenue: revenue minus returns.cashCollectedandcreditTotal: what was paid in cash and what was sold on credit.
With expand=summary you also get dailyBreakdown, with one row for every day in the range,
newest day first. Each row has date, revenue, transactions, returns, discount,
netSales and averageOrderValue. The breakdown is paged by page and size. Keep
requesting while dailyBreakdown.hasNext is true.
Add registerId to limit the revenue, transaction, discount, cash and credit totals to one
register. totalReturns, netRevenue and the daily breakdown still cover every register.
Endpoint: Get sales summary
Step 2 — Split sales by store
See which stores the revenue came from.
curl 'https://beta.iotoms.com/api/v1/reports/sales/by-store?from=2026-10-01&to=2026-10-18' \
-H 'X-TenantID: <tenant-code>' \
-H 'Authorization: Bearer <token>'data is a plain list with one row per store, highest revenue first. Each row has storeId,
transactionCount, revenue, vatAmount and netRevenue (revenue minus VAT). Match
storeId to the store IDs from List stores.
Sales recorded without a store are grouped in one row with an empty storeId.
Endpoint: Get sales by store
Step 3 — Page through sales by item
This report has one row per item sold, so it can run to many pages.
curl 'https://beta.iotoms.com/api/v1/reports/sales/by-item?from=2026-10-01&to=2026-10-18&page=0&size=100' \
-H 'X-TenantID: <tenant-code>' \
-H 'Authorization: Bearer <token>'Each row in data.content has:
| Field | Meaning |
|---|---|
itemId, itemName | The item |
categoryName, brandName | Where it sits in the catalog |
qtySold | Quantity sold in the period |
totalRevenue | Sum of the line totals for this item |
totalDiscount | Discount given on those lines |
netRevenue | totalRevenue − totalDiscount |
returnQty | Currently always 0. Use totalReturns from Step 1 for returns |
To fetch every row, start at page=0 and add 1 each time. Stop once data.page.number + 1
equals data.page.totalPages, or when a page comes back empty. Keep from, to and size
the same on every request. The rows are not sorted in a fixed order, so de-duplicate by
itemId when you combine the pages.
Endpoint: Get sales by item
Step 4 — Export current stock for every item
The balance report lists stock on hand for every item that has a stock record, as it stands right now. An item that has never been stocked does not appear.
curl 'https://beta.iotoms.com/api/v1/reports/inventory/balance?page=0&size=100' \
-H 'X-TenantID: <tenant-code>' \
-H 'Authorization: Bearer <token>'Each row in data.content has itemId, itemName and categoryName, and these quantities in
the item's base unit:
quantityOnHand: the total held.reservedQuantity: the amount held by reservations.availableQuantity: what is free to sell.
Each row also has minimumStockLevel, isLowStock and lastAdjustedAt. It can include
unitCost and totalValue. Page through it the same way as Step 3. Rows come most recently
adjusted first, so an item adjusted during your export can move between pages. Run the export
when stock is quiet, or de-duplicate by itemId.
This report has no date filter. For stock on a past date, call
Get inventory balance on a past date
with asOfDate. It returns itemId, itemName and quantityOnHand as at the end of that
day (UTC), for each item with recorded stock movements, sorted by itemId. It is not paged.
Endpoint: List current inventory balances