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

Tool	Description	Key Parameters
sherweb_billing_payable_charges	Get payable charges for a date range	billingCycleType (OneTime|Monthly|Yearly), periodFrom, periodTo, page, pageSize
sherweb_billing_charge_details	Get detailed breakdown of a specific charge	chargeId (required)

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:

Charge Type	Description	When Generated
Setup	One-time provisioning or activation fees	When a new subscription is created
Recurring	Ongoing subscription charges	Each billing cycle (monthly/yearly)
Usage	Consumption-based charges (e.g., Azure metered)	Based on actual usage during the period

Billing Cycles

Cycle	Description	Charge Frequency
OneTime	Single charge, no recurrence	Once at setup
Monthly	Charged every month	Monthly billing period
Yearly	Charged annually	Annual billing period

Pricing Breakdown

Every charge in Sherweb includes a detailed pricing structure:

Field	Type	Description
listPrice	decimal	Vendor's published list price per unit
netPrice	decimal	Partner's net price after distributor discounts
quantity	integer	Number of units (seats, licenses, etc.)
prorated	boolean	Whether the charge is prorated for a partial period
proratedDays	integer	Number of days in the prorated period
subTotal	decimal	Calculated subtotal before deductions (netPrice x quantity)

Deductions

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

Deduction Type	Description	Calculation
PromotionalMoney	Fixed dollar amount promotional discount	Subtracted from subTotal
PromotionalPercentage	Percentage-based promotional discount	Percentage off subTotal
PerformancePercentage	Performance-based rebate for hitting volume targets	Percentage off subTotal

Fees and Taxes

After deductions, additional line items may apply:

Item	Description
fees	Administrative or platform fees added by Sherweb
taxes	Applicable sales tax, GST, HST, or VAT
total	Final amount payable (subTotal - deductions + fees + taxes)

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

Field	Type	Description
id	string	Charge unique identifier
customerId	string	Customer the charge belongs to
customerName	string	Customer display name
subscriptionId	string	Associated subscription
productName	string	Product or SKU name
chargeType	string	Setup, Recurring, or Usage
billingCycle	string	OneTime, Monthly, or Yearly
listPrice	decimal	Vendor list price per unit
netPrice	decimal	Partner net price per unit
quantity	integer	Number of units
prorated	boolean	Whether charge is prorated
proratedDays	integer	Days in prorated period
subTotal	decimal	Subtotal before deductions
deductions	array	List of applied deductions
fees	decimal	Additional fees
taxes	decimal	Tax amount
total	decimal	Final payable amount

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

Error	Cause	Resolution
No charges found	The periodFrom/periodTo window contains no charges, or the wrong billingCycleType was requested	Widen the date range and re-check the cycle type. There is no period list to validate against — the window is whatever you passed
Charge details unavailable	Charge ID does not exist	Verify the charge ID from the sherweb_billing_payable_charges result
Authentication error	Expired or invalid token	Re-authenticate using OAuth 2.0 client credentials flow

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