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

# Background Jobs

> The in-process scheduler: insight generation, order catch-up sync, daily rollups, plan usage reconciliation, and retention pruning.

Background work runs on **node-cron inside the web process** — there is no
separate worker. The scheduler initializes lazily on the first admin page
load, is idempotent per process, and iterates every store that has settings.
It can be disabled entirely with the `SCHEDULER_DISABLED=1` environment
variable (useful for multi-process deployments where only one instance should
run jobs). Per-shop failures are isolated: one store's error never stops
another store's run.

## Schedule (all times UTC)

| Cadence | Jobs |
| - | - |
| Every 30 minutes | Generate insights; order catch-up sync |
| Hourly at :15 | Volume watermark guard (keeps the order-sync watermark sane after clock or watermark drift) |
| Daily at 02:10 | Retention pruning |
| Daily at 02:25 | Trend rollups: aggregate recent days into daily stats, prune beyond the retention window |
| Daily at 02:40 | Usage reconcile: recompute estimated storage bytes from real row counts |
| Daily at 02:50 | Insight feed pruning (dismissed >30 days, stale >180 days) |
| Weekly, Monday 03:20 | BYTES\_PER\_EVENT calibration |
| Daily at 04:00 | Billing re-verification through the Shopify Partner API |

> [!NOTE]
>
> Timing expectations that follow from this schedule: insights can be up to 30 minutes behind, and a fresh checkout appears
> in dashboards within about a minute thanks to the throttled order sync.

## Insight generation

Every 30 minutes the app evaluates finding rules per store — high views with
low cart, high cart with low purchase, low stock with high interest, best
promotional window, restock suggestions, and related types. Each finding
stores its evidence, the period it covers, and a suggested next step. The same
insight type for the same product is suppressed for **24 hours** so the feed
stays fresh, and merchants can dismiss findings or trigger detection manually
from the [Insights page](https://topten.mintlify.site/guides/insights.md).

## Order catch-up sync

Webhooks are the primary order path; the sync is the reconciliation layer:

* **First run for a store:** backfills roughly 90 days of orders through the
  Admin GraphQL API.
* **Subsequent runs:** fetches only orders updated since the last watermark,
  with a 1-hour overlap to heal edits and missed webhooks.
* **Triggers:** the 30-minute cron, plus a throttled check (at most once per
  minute per store) when the admin is open.
* **Attribution limit:** Admin API order queries expose no cart token, so
  synced orders count as orders but can never be attributed — attribution
  stays webhook-driven. The UI says so rather than implying coverage.

## Rollups and retention

* The nightly rollup job aggregates recent days' events and orders into
  per-product daily stats (views, sessions, cart events, orders, units,
  attributed orders, net revenue) with idempotent upserts, so re-runs heal
  instead of duplicating. Rollups are the long-term record: raw events are
  pruned after the retention window, rollups are not.
* The retention job deletes events, sessions, and orders older than the configured retention (default 90 days) and sweeps
  presence rows past a hard 7-day backstop. See
  [Data model](https://topten.mintlify.site/architecture/data-model.md) for the full lifecycle and deletion
  matrix.
* Billing housekeeping runs nightly: usage storage estimates are reconciled from real row counts, and plan status is re-verified against the Partner API so quota enforcement stays honest.


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