Guide

Usage and invoices

Read daily and monthly usage per device and customer, export it as CSV, and run your monthly invoices.

Two sources of usage

Every usage figure carries a basis that says where it came from:

Basis	From	Use it for
`api`	The network provider, polled every hour	Day-to-day monitoring and alerts. Close to final, not billed.
`cdr`	The provider's monthly records, after the month ends	Billing. These are the figures invoices use.

A past month is closed once its provider records are all in; from then on its cdr figures are final. List closed months tells you which. Sizes are bytes, periods are UTC days or months.

Totals per device and customer

Usage aggregates are ready-made totals. Pick a granularity (daily or monthly) and a scope_type: device, customer, or reseller for your whole business. Each customer's September, as billed:

Request

curl -g "https://api.houndsat.com/api/json/usage_aggregates?filter[granularity]=monthly&filter[scope_type]=customer&filter[basis]=cdr&filter[period_start]=2026-09-01" \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN"

One aggregate

{
  "type": "usage_aggregate",
  "id": "…",
  "attributes": {
    "granularity": "monthly",
    "scope_type": "customer",
    "scope_id": "c41e9a03-6b2f-4d8e-a571-0f3b9c2d7e14",
    "period_start": "2026-09-01",
    "basis": "cdr",
    "uplink_bytes": 412880,
    "downlink_bytes": 96120,
    "total_bytes": 509000,
    "active_device_count": 3,
    "retail_cost_cents": 4500,
    "wholesale_cost_cents": 2700,
    …
  }
}

active_device_count counts devices that were active on at least one day of the period. The cost fields are filled once the month's invoices are issued: retail_cost_cents is what you bill the customer, wholesale_cost_cents what HoundSat bills you. Your customers never see your wholesale cost, and Staff see no costs at all.

Daily records

For the raw numbers, usage records give one device's usage on one day, with uplink and downlink separately:

One device this month

curl -g "https://api.houndsat.com/api/json/usage_records?filter[device_id]=5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8&filter[usage_date][greater_than_or_equal]=2026-10-01" \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN"

Usage stays with the customer a device belonged to that day, so moving a device to another customer never moves its past usage.

CSV exports

The same aggregates as a spreadsheet, for finance or a data warehouse. Rows and cost columns follow the same visibility rules as the API.

Monthly usage per customer, as CSV

curl -g "https://api.houndsat.com/api/exports/usage.csv?granularity=monthly&scope_type=customer&from=2026-01-01&to=2026-09-30&basis=cdr" \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN" \
  -o usage-2026.csv

The monthly invoice cycle

The month closes. Once its provider records are in, HoundSat generates its invoices as drafts: a retail invoice from you to each customer, priced on your retail plans, and a wholesale invoice from HoundSat to you.
You review and finalize your retail drafts. Finalizing assigns the invoice number and sets it due 14 days later.
Your customer pays from their portal, or you mark it paid when you're paid another way.

Made a mistake? Void a draft or open invoice and the next invoice run of that month issues a new one.

September's retail drafts

curl -g "https://api.houndsat.com/api/json/invoices?filter[kind]=retail&filter[status]=draft&filter[period]=2026-09-01" \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN"

Finalize one

curl -X PATCH https://api.houndsat.com/api/json/invoices/6c0a8e2d-9f4b-4b17-a3c6-2e7d5f1b9a04/finalize \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{"data": {"type": "invoice", "id": "6c0a8e2d-9f4b-4b17-a3c6-2e7d5f1b9a04", "attributes": {}}}'

Preview this month

Before a month closes, the preview shows what its invoices would be right now, from the hourly api figures: one group per customer, one line per device, with totals. Use kind=retail for what you'll bill your customers and kind=wholesale for what HoundSat will bill you.

Request

curl "https://api.houndsat.com/api/json/invoices/preview?kind=retail" \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN"