# Requirements: PAX8 Integration (v2.0)

**Defined:** 2026-07-10
**Core Value:** Managers can see PAX8 subscription costs and seat counts alongside existing Autotask company data in Pulse, without manually cross-referencing PAX8's own portal.
**Source:** `.planning/seeds/SEED-002-pax8-integration.md` (scoped via `/gsd-explore` on 2026-07-10)

## v2.0 Requirements

Requirements for this milestone. Each maps to a roadmap phase.

### PAX8 — Client & Auth

- [x] **PAX8-01**: Pulse authenticates to the PAX8 REST API (`api.pax8.com/v1`) via OAuth2 client-credentials, using the developer-provisioned client ID/secret
- [x] **PAX8-02**: `isPax8Configured()` helper reports whether PAX8 credentials are present, following the existing `is<Name>Configured()` factory pattern (`lib/services/pax8-factory.ts`)

### PAX8 — Data Sync

- [x] **PAX8-03**: Pulse syncs PAX8 companies into Postgres
- [x] **PAX8-04**: Pulse syncs PAX8 subscriptions (product, seat count, billing term) into Postgres
- [x] **PAX8-05**: Pulse syncs PAX8 product catalog (SKUs, categories) into Postgres, so subscriptions are human-readable
- [x] **PAX8-06**: Pulse syncs PAX8 orders/invoices (historical line items) into Postgres, enabling cost reconciliation over time, not just current-state seats
- [x] **PAX8-07**: Sync runs on a daily schedule via the existing `sync-scheduler.ts` cron pattern
- [x] **PAX8-08**: All PAX8 sync operations are read-only — no writes back to the PAX8 API (no seat adjustments, no order placement)
- [x] **PAX8-09**: PAX8 integration can be toggled on/off via `/admin/integrations`, consistent with other integrations (`integration_settings` table)

### PAX8 — Company Matching

- [x] **PAX8-10**: PAX8 companies are automatically matched to existing Autotask companies by fuzzy name similarity at sync time
- [x] **PAX8-11**: Unmatched or ambiguous company matches are flagged rather than silently guessed
- [ ] **PAX8-12**: An admin can view flagged/ambiguous company matches and manually resolve them to the correct Autotask company

### PAX8 — UI Surface

- [ ] **PAX8-13**: A new `/pax8` page lists PAX8 companies with their subscriptions and a cost breakdown
- [ ] **PAX8-14**: The `/pax8` page surfaces flagged/ambiguous company matches (PAX8-11) for manual resolution

## Future Requirements

<!-- Deferred — not this milestone. -->

- Write access to PAX8 (seat adjustments, order placement) — no concrete need identified yet; revisit only if reconciliation surfaces one
- Domain-based or external-ID-based company matching, if research resolves [[RESEARCH-pax8-company-identifiers]] in `.planning/research/questions.md` and finds a more stable join key than name
- General Pulse data assistant (chatbot) consuming this data — separate future milestone, see `.planning/seeds/SEED-003-general-pulse-data-assistant.md`

## Out of Scope

<!-- Explicit exclusions with reasoning. -->

- Write-back to PAX8 — this integration is read-only in v2.0, matching the pattern of most existing Pulse integrations (RMM, IT Glue, Veeam)
- Chatbot/NL query layer — deliberately separated into SEED-003 so this milestone stays scoped to the data sync itself

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| PAX8-01 | Phase 10 | Complete |
| PAX8-02 | Phase 10 | Complete |
| PAX8-03 | Phase 11 | Complete |
| PAX8-04 | Phase 11 | Complete |
| PAX8-05 | Phase 11 | Complete |
| PAX8-08 | Phase 11 | Complete |
| PAX8-06 | Phase 12 | Complete |
| PAX8-10 | Phase 12 | Complete |
| PAX8-11 | Phase 12 | Complete |
| PAX8-07 | Phase 13 | Complete |
| PAX8-09 | Phase 13 | Complete |
| PAX8-12 | Phase 14 | Pending |
| PAX8-13 | Phase 14 | Pending |
| PAX8-14 | Phase 14 | Pending |

**Coverage:** 14/14 v2.0 requirements mapped ✓

---
*Requirements defined: 2026-07-10*
