Sherweb Billing

Sherweb Distributor Billing

Overview

Billing in Sherweb represents the financial data flowing from the distributor to the service provider (MSP). When Sherweb provisions or manages cloud subscriptions on behalf of an MSP's customers, it generates payable charges dated within a billing period. Each charge includes detailed pricing breakdown with list prices, net prices, proration, deductions (promotional and performance), fees, and taxes. Understanding Sherweb billing data is critical for MSPs to calculate margins, reconcile costs, and ensure accurate client billing. Note that the tool surface reaches charges, not periods and not invoices — see What this plugin cannot retrieve.

Anti-triggers

• An invoice the MSP sends to a client — Sherweb charges are money the MSP owes the distributor, the opposite direction to the accounting and PSA plugins. Client-facing invoices are qbo-invoices, xero-invoices, autotask-billing, or halopsa-invoices. Getting the direction wrong inverts every margin calculation.
• The equivalent cost from the other CSP marketplace — use pax8-invoices.
• Comparing the two sides to find unbilled subscriptions — that is the cross-vendor reconciliation itself; use shared-skills-billing-reconciliation.
• Aged receivables on the MSP's own books — Sherweb's per-customer AR view is the distributor platform's ledger, not the accounting system's. Collections work runs off qbo-reports or xero-reports; see sherweb-customers for what Sherweb's own AR data covers.

MCP Tools

Available Tools

The server registers exactly two billing tools (sherweb-mcp/src/domains/billing.ts:17-69).

What this plugin cannot retrieve

Two capabilities that earlier revisions of this skill described do not exist on the shipped server. Do not substitute a near-miss for either.

• There is no billing-period enumeration. No tool lists available billing periods, their IDs, dates, or open/closed status. You supply the window yourself as periodFrom/periodTo on sherweb_billing_payable_charges; you cannot ask the server which periods exist. If an operator says "the latest period", resolve that from the calendar and the MSP's own billing cycle, then pass explicit dates — never guess a billingPeriodId, which is not a parameter of any tool here.
• There is no invoice surface at all. Nothing on this server lists invoices, fetches an invoice by ID, or returns invoice line items. The two invoice-adjacent capabilities are narrower and are not substitutes: sherweb_billing_charge_details returns the line items of a single charge by charge ID, and sherweb_customers_accounts_receivable returns a customer's outstanding balance and aging. Neither is an invoice. When an operator asks for a Sherweb invoice, say so plainly and offer charge-level reconciliation or the AR balance instead. Invoice documents live in the Sherweb partner portal.

Get Payable Charges

Call sherweb_billing_payable_charges with an explicit date range:

• periodFrom / periodTo: ISO 8601 dates bounding the window (e.g. 2026-02-01 to 2026-02-28). You choose these; there is no period list to pick from.
• billingCycleType: OneTime, Monthly, or Yearly. If you call the tool with none of billingCycleType, periodFrom, or periodTo, the server elicits the cycle type from the caller before proceeding.
• Paginate: Set page (1-based) and pageSize for large result sets
• Returns all charges in the window with full pricing breakdown

Example: Get monthly recurring charges for February 2026:

• sherweb_billing_payable_charges with billingCycleType=Monthly, periodFrom=2026-02-01, periodTo=2026-02-28, pageSize=100

Get Charge Details

Call sherweb_billing_charge_details with the chargeId of a charge returned by sherweb_billing_payable_charges to see its line items, pricing tiers, deductions, fees, and tax.

Key Concepts

Charge Types

Sherweb categorizes charges into three types:

Billing Cycles

Pricing Breakdown

Every charge in Sherweb includes a detailed pricing structure:

Deductions

Sherweb applies deductions to reduce the partner's cost. Deductions come in three types:

Fees and Taxes

After deductions, additional line items may apply:

MSP Margin Calculation

To calculate your MSP margin on a Sherweb charge:

MSP Cost     = charge.total (what you pay Sherweb)
Client Price = your retail price to the customer
Margin       = Client Price - MSP Cost
Margin %     = (Margin / Client Price) * 100

Tips for margin analysis:

1. Compare listPrice vs netPrice to see your distributor discount
2. Factor in deductions -- promotional discounts reduce your cost
3. Performance percentage deductions reward volume; track these quarterly
4. Setup charges are one-time -- amortize across the subscription term for accurate monthly margin
5. Usage charges fluctuate -- use historical averages for margin forecasting

Field Reference

Payable Charge Fields

No invoice fields are documented here because no tool on this server returns an invoice. See What this plugin cannot retrieve, above.

Common Workflows

Monthly Billing Reconciliation

1. Determine the window you want from the calendar — there is no period list to read it from
2. Call sherweb_billing_payable_charges with periodFrom and periodTo set to that window and billingCycleType set to the cycle you are reconciling, paginating through all results
3. Group charges by customerId to see per-customer totals
4. Compare Sherweb charges against what you bill each customer in your PSA
5. Flag discrepancies where MSP cost exceeds or is too close to client billing

Margin Analysis Across Customers

1. Fetch all payable charges for the date range
2. For each customer, sum the total field across all charges
3. Compare against your retail billing to that customer
4. Calculate margin per customer and overall portfolio margin
5. Identify customers with negative or sub-target margins

Deduction Tracking

1. Fetch payable charges and filter for entries with non-empty deductions arrays
2. Group deductions by type (PromotionalMoney, PromotionalPercentage, PerformancePercentage)
3. Sum total savings from each deduction category
4. Track performance percentage deductions over time to monitor volume rebate trends

Charge Verification (there is no invoice verification workflow)

Invoice retrieval is not available through this plugin — see What this plugin cannot retrieve. Verify at the charge level instead:

1. Call sherweb_billing_payable_charges for the window under review
2. For each charge worth scrutiny, call sherweb_billing_charge_details with its chargeId to see the line items, deductions, fees, and tax
3. Cross-reference those line items against what you expected to be provisioned
4. Verify totals and flag discrepancies. To confirm the invoice document itself, open it in the Sherweb partner portal — no tool here returns it.

Cost Forecasting

1. Pull 3-6 months of history by calling sherweb_billing_payable_charges once per month, with periodFrom/periodTo bounding each month explicitly
2. Calculate average monthly cost per customer and per product
3. Identify trends (growing seat counts, new products, usage spikes)
4. Project next month's Sherweb costs for budget planning

Response Examples

Payable Charge:

{
  "id": "chg-2026-02-001",
  "customerId": "cust-abc-123",
  "customerName": "Acme Corporation",
  "subscriptionId": "sub-def-456",
  "productName": "Microsoft 365 Business Premium",
  "chargeType": "Recurring",
  "billingCycle": "Monthly",
  "listPrice": 22.00,
  "netPrice": 17.10,
  "quantity": 25,
  "prorated": false,
  "proratedDays": null,
  "subTotal": 427.50,
  "deductions": [
    {
      "type": "PerformancePercentage",
      "description": "Volume rebate - Gold tier",
      "percentage": 3.0,
      "amount": 12.83
    }
  ],
  "fees": 0.00,
  "taxes": 33.17,
  "total": 447.84
}

Error Handling

Common Errors

Best Practices

1. Track deductions - Monitor promotional and performance deductions to ensure you receive expected discounts
2. Watch for proration - Prorated charges indicate mid-cycle changes; verify they match subscription modifications
3. Separate charge types - Analyze Setup, Recurring, and Usage charges independently for accurate cost modeling
4. Calculate true margin - Include fees and taxes in margin calculations, not just netPrice vs listPrice
5. Monitor usage charges - Usage-based charges (Azure, etc.) can spike unexpectedly; set up alerts
6. Plan for billing cycles - Annual charges create cash flow events; plan for yearly renewal months
7. Use performance rebates strategically - Consolidate purchasing through Sherweb to maximize performance percentage deductions

Related Skills

• Sherweb API Patterns - Authentication, endpoints, and rate limits
• Sherweb Customers - Customer management and hierarchy
• Sherweb Subscriptions - Subscription lifecycle and quantity management