/reconcile-billing

description: Compare Pax8 subscriptions against Xero or QBO invoices to find billing gaps
argument-hint: "<company> <accounting> [period] [threshold]"
arguments: [company, accounting, period, threshold]

Reconcile Billing

Compare active Pax8 subscriptions against Xero or QuickBooks Online invoices for a client (or all clients) to find unbilled subscriptions, quantity mismatches, and margin discrepancies.

Prerequisites

• Pax8 API access configured (subscriptions and companies endpoints)
• At least one accounting platform configured:
• **Xero**: API access with invoices and contacts scopes
• **QuickBooks Online**: API access with invoice and customer read permissions

Steps

1. **Resolve the billing period**

• Parse the `--period` argument into a start and end date
• `2026-02` becomes `2026-02-01` to `2026-02-28`
• `last-month` calculates the previous calendar month from today
• `last-quarter` calculates the previous three calendar months

2. **Pull Pax8 subscriptions**

• If `--company` is a specific name: search Pax8 companies by name, get the company ID, then fetch active subscriptions for that company
• If `--company` is "all": fetch all Pax8 companies, then fetch active subscriptions for each
• For each subscription, resolve the product name via `/v1/products/{productId}`
• Build a subscription ledger: company name, product name, quantity, unit price, monthly total

   # Get company ID
   curl -s "https://api.pax8.com/v1/companies?name=Acme" \
     -H "Authorization: Bearer $PAX8_TOKEN"

   # Get active subscriptions for company
   curl -s "https://api.pax8.com/v1/subscriptions?companyId={companyId}&status=Active&page=0&size=200" \
     -H "Authorization: Bearer $PAX8_TOKEN"

   # Resolve product name
   curl -s "https://api.pax8.com/v1/products/{productId}" \
     -H "Authorization: Bearer $PAX8_TOKEN"

3. **Pull invoices from the accounting platform**

**If `--accounting xero`:**

• Search Xero contacts by company name to get the ContactID
• Fetch ACCREC invoices for that contact within the billing period
• Extract line items with Description, Quantity, UnitAmount, LineAmount

   # Find contact
   curl -s "https://api.xero.com/api.xro/2.0/Contacts?where=Name==%22Acme%20Corporation%22" \
     -H "Authorization: Bearer $XERO_TOKEN" \
     -H "xero-tenant-id: $XERO_TENANT_ID"

   # Get invoices for period
   curl -s "https://api.xero.com/api.xro/2.0/Invoices?where=Contact.ContactID==guid(%22{contactId}%22)&&Type==%22ACCREC%22&&Date>=DateTime(2026,2,1)&&Date<=DateTime(2026,2,28)" \
     -H "Authorization: Bearer $XERO_TOKEN" \
     -H "xero-tenant-id: $XERO_TENANT_ID"

**If `--accounting quickbooks`:**

• Query QBO customers by display name to get the customer ID
• Query invoices for that customer within the billing period
• Extract line items with Description, Qty, UnitPrice, Amount

   # Find customer
   curl -s -H "Authorization: Bearer $QBO_TOKEN" \
     "https://quickbooks.api.intuit.com/v3/company/$QBO_REALM_ID/query?query=SELECT * FROM Customer WHERE DisplayName = 'Acme Corporation'"

   # Get invoices for period
   curl -s -H "Authorization: Bearer $QBO_TOKEN" \
     "https://quickbooks.api.intuit.com/v3/company/$QBO_REALM_ID/query?query=SELECT * FROM Invoice WHERE CustomerRef = '{customerId}' AND TxnDate >= '2026-02-01' AND TxnDate <= '2026-02-28'"

4. **Match subscriptions to invoice line items**

• For each Pax8 subscription, search the client's invoice line items for a match
• Matching criteria (applied in order):

1. Product name fuzzy match (contains, token match, abbreviation expansion) 2. Quantity comparison (exact or within threshold) 3. Amount comparison (within `--threshold` tolerance)

• Record each subscription as: matched, unmatched (gap), or discrepancy

5. **Identify and classify findings**

• **CRITICAL**: Active subscription with no matching invoice line (revenue leakage)
• **HIGH**: Quantity mismatch greater than 10%
• **MEDIUM**: Price discrepancy greater than `--threshold` percent
• **LOW**: Name mismatch requiring manual confirmation
• **INFO**: Cancelled Pax8 subscription still appearing on invoice

6. **Also check for cancelled subscriptions still being billed**

• Fetch Pax8 subscriptions with `status=Cancelled` for the company
• Check if any cancelled product names still appear on the invoice
• Flag as INFO severity

7. **Output the reconciliation report**

• Summary with totals: companies checked, subscriptions matched, gaps found by severity
• Detailed findings grouped by severity
• Estimated revenue impact for each gap
• Suggested action for each finding

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | company | string | Yes | - | Company name or "all" | | accounting | string | Yes | - | "xero" or "quickbooks" | | period | string | No | last-month | Billing period (YYYY-MM, last-month, last-quarter) | | threshold | string | No | 5 | Minimum discrepancy % to flag |

Examples

Single Company Against Xero

/reconcile-billing "Acme Corporation" --accounting xero

Pulls all active Pax8 subscriptions for Acme Corporation, fetches their February Xero invoices, matches each subscription to an invoice line item, and reports any gaps or discrepancies.

Full Portfolio Against QuickBooks

/reconcile-billing "all" --accounting quickbooks

Iterates through every Pax8 company, fetches their QuickBooks invoices for last month, and produces a portfolio-wide reconciliation report. This may take several minutes for large client bases due to API pagination.

Specific Period with Custom Threshold

/reconcile-billing "Acme Corporation" --accounting xero --period "2026-01" --threshold "3"

Reconciles January 2026 billing for Acme Corporation, flagging any discrepancies greater tha