> ## Documentation Index
> Fetch the complete documentation index at: https://docs.letshum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Order & Commission Reporting

> Retrieve order status, installation state, commissions, and checkout progression

# Order & Commission Reporting

The analytics endpoints provide partner-scoped session, order, commission, and cart-progression data. Analytics requests are limited to 60 requests per minute per IP.

<Warning>
  The order and installation fields on this page describe Hum's partner analytics and widget workflow. They do not map directly to the evidence-based fulfillment states returned by the [Hum Broadband MCP](/mcp/ordering-and-recovery#fulfillment-states). In particular, an MCP result such as `queued` or `accepted_by_fulfillment` is not an ISP acceptance or installation confirmation.
</Warning>

## List Sessions

`GET /analytics/sessions` returns 50 sessions per page. Use the `page` parameter and `meta.pages` to traverse pages; `meta.count` is the total number of matching sessions.

Available filters:

* `start_date` and `end_date`: Limit sessions by creation time.
* `updated_since`: Return sessions whose session or order changed on or after the supplied time, ordered by most recent change first.
* `token_ids[]`: Restrict results to API tokens owned by your account. A token you do not own returns HTTP 403.
* `with_clicks`: When `true`, return only sessions with click activity.

```bash cURL theme={null}
curl --get https://api-sandbox.letshum.com/analytics/sessions \
  -H "Authorization: Bearer hum_sandbox_XXXXXXXXXXXXXXXXXXXXXXXXXX" \
  --data-urlencode "updated_since=2026-07-13T12:00:00Z" \
  --data-urlencode "page=1"
```

See [List Sessions](/api-reference/analytics/list-sessions) for the response schema and all parameters.

## Get Session Detail

`GET /analytics/sessions/{id}` returns one session and adds:

* `order`: The associated order, or `null` when no order was placed.
* `cart_progression`: The full checkout-step timeline ordered by timestamp.

See [Get Session Detail](/api-reference/analytics/get-session-detail).

## Move-in vs Move-out Traffic

Every session returned by both analytics endpoints carries a `context` field of either
`move_in` or `move_out`.

Context is set by the API token that created the session, not by a request parameter. If you
run both flows, you are issued a separate token for each, and each session inherits the
context of the token behind it. Sessions created before this field was introduced return
`move_in`.

* `move_in`: a resident setting up service at a home they are moving into.
* `move_out`: a resident leaving your property and setting up service at their next home.

There is no `context` filter parameter. To report on one context, either request that token's
traffic with `token_ids[]`, or group client-side on the `context` field.

<Warning>
  A move-out session's address is the resident's **destination** home, not your building. Do
  not roll move-out addresses up into property-level or building-level reporting.
</Warning>

## Order Fields

The order object includes:

* `order_number`: Unique order identifier.
* `status`: `draft`, `submitted`, `processing`, `confirmed`, `complete`, or `cancelled`.
* `ordered_at`: When the order was submitted.
* `installed`: Whether service has been installed.
* `installed_at`: Installation timestamp, or `null` when not installed.
* `commission_cents`: Locked commission amount in cents, or `null` when no commission is recorded.

The normal progression is `draft` → `submitted` → `processing` → `confirmed` → `complete`. `cancelled` is final. For cancelled orders, `installed` is always `false`, while `installed_at` and `commission_cents` are `null`.

## Reconciling Widget Orders

The `orderId` in the widget's `humOrderCompleted` event is the same value as `order_number` in the analytics endpoints. Use it to join widget conversions to order and commission rows. The session's `campaign_id` provides session-level attribution.

## Keep a Local Copy Current

The API does not send server-side webhooks for analytics changes. Poll with `updated_since` set to the time of your last successful sync and page through all results. A session is returned whenever the session or its order changed, including installs, cancellations, and commission updates on older sessions.

Treat each returned row as authoritative and overwrite your stored copy. Do not use `start_date` as a sync cursor: it filters by session creation time, so later status changes to older sessions do not appear.

```text Sync loop theme={null}
cursor = last_successful_sync_time

repeat:
  sync_started_at = current_time()
  page = 1

  do:
    response = GET /analytics/sessions?updated_since=cursor&page=page
    overwrite_local_rows(response.data)
    page = page + 1
  while page <= response.meta.pages

  cursor = sync_started_at
  save_last_successful_sync_time(cursor)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.