/billing-reconciliation

name: Cross-Vendor Billing Reconciliation
description: >
  Reconciling cloud marketplace subscriptions (Pax8) against accounting
  invoices (Xero, QuickBooks Online): the matching strategy, billing gaps,
  unbilled subscriptions, and margin discrepancy analysis.
when_to_use: >-
  When comparing marketplace subscription data against issued invoices to
  find revenue leakage. Use when: billing reconciliation, reconcile
  subscriptions, unbilled subscriptions, billing gap analysis, margin
  analysis, subscription vs invoice comparison, pax8 xero reconciliation, or
  pax8 quickbooks reconciliation.

Cross-Vendor Billing Reconciliation

Overview

MSPs purchase cloud subscriptions through distributors like Pax8 and resell them to clients, billing through an accounting platform such as Xero or QuickBooks Online. Revenue leakage occurs when active subscriptions are not reflected on client invoices -- a common problem as seat counts change, new products are provisioned, or billing staff miss updates. This skill teaches Claude how to systematically compare Pax8 subscription data against accounting invoices to identify billing gaps, quantity mismatches, price discrepancies, and margin erosion.

The reconciliation answers one fundamental question: **"Is every active Pax8 subscription being billed to the correct client at the correct quantity and price?"**

Anti-triggers

This is a shared skill: it owns the *comparison across two platforms*. Anything that lives inside one platform belongs to that platform's skill.

• **Reading subscriptions or marketplace charges** — use

`pax8-subscriptions`, `pax8-invoices`, `sherweb-subscriptions`, or `sherweb-billing`.

• **Reading or creating an accounting invoice** — use

`qbo-invoices`, `qbo-reports`, `xero-invoices`, or `xero-reports`.

• **Chasing an invoice the client has not paid** — that is collections

against a single system, not a reconciliation; use `qbo-reports` or `xero-reports` for the aged-receivables view.

• **Recovering the gap once it is found** — this skill identifies unbilled

and mispriced subscriptions. Issuing the corrected invoice is a write against the accounting platform, and changing a seat count is a write against the marketplace. Hand off; do not let one analysis run make both kinds of change.

Reconciliation Workflow

Step 1: Pull Active Pax8 Subscriptions with Pricing

Fetch all active subscriptions from Pax8, grouped by company. Each subscription includes product name, quantity (seat count), unit price, billing term, and status.

GET /v1/subscriptions?status=Active&page=0&size=200
Authorization: Bearer YOUR_TOKEN

For a specific company:

GET /v1/subscriptions?companyId={companyId}&status=Active&page=0&size=200

**Key fields to extract per subscription:**

• `companyId` -- resolve to company name via `/v1/companies/{companyId}`
• `productId` -- resolve to product name via `/v1/products/{productId}`
• `quantity` -- number of seats/licenses
• `price` -- unit price (your cost from Pax8)
• `billingTerm` -- Monthly or Annual
• `startDate` / `endDate` -- subscription period
• `status` -- confirm Active

**Build a subscription ledger:**

Pax8 Subscription Ledger
────────────────────────────────────────────────
Company          Product                    Qty  Unit Price  Monthly Total
Acme Corp        M365 Business Premium       25     $17.10       $427.50
Acme Corp        Azure AD P1                 25      $7.50       $187.50
Acme Corp        Acronis Backup 500GB         1     $85.00        $85.00
Beta LLC         M365 Business Basic         10      $7.20        $72.00
Beta LLC         SentinelOne Complete        15     $4.00         $60.00
────────────────────────────────────────────────

Step 2: Pull Recent Invoices from Accounting Platform

Xero

Fetch sales invoices (ACCREC) for the billing period:

curl -s -X GET "https://api.xero.com/api.xro/2.0/Invoices?where=Type==%22ACCREC%22&&Date>=DateTime(2026,2,1)&&Date<=DateTime(2026,2,28)" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "xero-tenant-id: ${XERO_TENANT_ID}" \
  -H "Accept: application/json"

For a specific contact (client):

curl -s -X GET "https://api.xero.com/api.xro/2.0/Invoices?where=Contact.ContactID==guid(%22${CONTACT_ID}%22)&&Type==%22ACCREC%22&&Date>=DateTime(2026,2,1)" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "xero-tenant-id: ${XERO_TENANT_ID}" \
  -H "Accept: application/json"

**Key fields:** `Contact.Name`, `LineItems[].Description`, `LineItems[].Quantity`, `LineItems[].UnitAmount`, `LineItems[].LineAmount`, `Invoice.Status`, `Invoice.Date`

QuickBooks Online

Query invoices for the billing period:

SELECT * FROM Invoice WHERE TxnDate >= '2026-02-01' AND TxnDate <= '2026-02-28' ORDERBY TxnDate DESC

For a specific customer:

SELECT * FROM Invoice WHERE CustomerRef = '123' AND TxnDate >= '2026-02-01'

**Key fields:** `CustomerRef.name`, `Line[].Description`, `Line[].SalesItemLineDetail.Qty`, `Line[].SalesItemLineDetail.UnitPrice`, `Line[].Amount`, `Balance`, `TxnDate`

Step 3: Match Subscriptions to Invoice Line Items

For each active Pax8 subscription, search the corresponding client's invoices for a matching line item. Matching uses a combination of product name, quantity, and amount (see Matching Strategy below).

**Matching priority:**

1. Company name match (Pax8 company to Xero contact / QBO customer) 2. Product name fuzzy match (subscription product to invoice line description) 3. Quantity comparison 4. Amount comparison (within tolerance)

Step 4: Identify Gaps -- Active Subscriptions with No Matching Invoice Line

Any active Pax8 subscription that cannot be matched to an invoice line item is a **billing gap**. These represent potential revenue leakage.

**Flag as CRITICAL:**

• Active subscription exists in Pax8
• No invoice line found in the accounting platform for this product/client combination in t