well_sum_receivables

io.github.WellApp-ai/well-mcp · Verify this server

What the workspace's customers still owe it: the outstanding receivables, one figure per currency, with the overdue part and an aging breakdown. It draws nothing. Use it for any total of what customers owe: "who owes us money", "how much are we owed", "how much is overdue". State the totals it returns and do not add up rows yourself, and do not page `well_query_records` to rebuild a total: this read sums every outstanding invoice on the server, so the same question gives the same figure each time. For the invoices behind the figure (which customer, which invoice), read the rows with `well_show_records`. **The rule is fixed, and `rule` echoes it.** An invoice counts as owed when the workspace is the issuer and the customer the receiver, it is a billing document (`rule.document_types`, or no type at all; never a proforma, quote, order or credit note), it is not a draft or canceled, its payment status is `unpaid` or `partial`, and `balance_due` is above zero. The amount is `balance_due`, so a part-paid invoice counts for what is left. Payment status decides, never `balance_due` alone: an invoice a connector calls settled keeps a balance until a bank payment matches it. **Every figure is per currency and never converted.** `currencies` holds one row per currency. Do not add two rows without converting them at a rate you can state. Each row has `outstanding_count` and `outstanding_total`, the `overdue_count` and `overdue_total` part past its due date, and `aging`: the bands `current` (not yet due, or due today), `1_30`, `31_60`, `61_90` and `over_90` days past due, every band present even at zero. The bands and the invoices with no due date add up to the outstanding total. **`as_of` is the instant of the read, and due dates are aged against `as_of_date`,** the UTC calendar date. Give `as_of` beside every figure. **What the figure leaves out is returned so you can say it:** - `no_due_date_count` and `no_due_date_total` (per row): outstanding invoices with no due date. They are in the outstanding total and in no aging band, and no other date stands in for a missing due date. - `marked_paid_count` and `marked_paid_total` (per row): issued invoices a connector says are settled with no bank payment matched yet, with a balance left. They are NOT in the outstanding total. State them on their own line. - `draft_count` and `draft_total` (per row): draft invoices with a balance left, at any payment status except `unknown`. A draft at `marked_paid` is counted here, not in the marked-paid line. An imported sales invoice often stays a draft while it is owed. They are NOT in the outstanding total. State them on their own line. - `unsettled_credit_note_count` and `unsettled_credit_note_total` (per row): issued credit notes still unpaid or part paid with a balance left. The read does not tell a note linked to its invoice from one that is not, so say "credit notes with a balance left", never "unlinked". They are NOT in the outstanding total and are NOT subtracted from it. State them on their own line. - `unknown_payment_status_count`: invoices, drafts included, whose payment status could not be worked out. Their balance is not trusted, so they are in no figure and in no draft line. `null` means the count failed, which is not `0`. - `unattributed_count`: outstanding-looking invoices Well could place on neither side. They may be owed to the workspace and are in no figure. `null` means the count failed, and it is also `null` when `customer_ids` narrows the read. - `no_currency_count`: invoices with no currency, among the outstanding ones and among the marked-paid, draft and credit-note lines. They are in no row. `null` means the count failed. - `no_balance_count`: unpaid or part-paid invoices, drafts included, with no `balance_due` recorded, so no amount to count. In no figure. `null` means the count failed. - `outstanding_payment_unknown_count`: invoices that ARE counted in `outstanding` and in its figure, but whose payment cannot be seen because the workspace holds no bank line within 90 days of their dates (`rule.outstanding_payment_unknown`). It is an "of which" of the outstanding count: never add it to a total, never list it as a held-back line, never subtract it from the figure. It is not `unknown_payment_status_count`: that count is a recompute that halted (balance not trusted, in no figure), while this one is counted in `outstanding` but no bank line covers the invoice's dates, so whether it was paid cannot be seen. Never say those invoices are unpaid for certain, and never say nothing is owed because no payment was matched. State it only when it is above 0: at 0 say nothing about it. `null` means the count failed. - `party_scope`: when `party_scope.side_unknown` is true the workspace has no resolved own company, so no side filter was applied: the figures cover every invoice on both sides, and the side is not known. Say the side is unknown, never that the figure is what customers owe. State every count beside the total, even at zero, so a reader can tell a clean read from a silent one, except `outstanding_payment_unknown_count`: it is an "of which" note, not a figure the reader asked for. Never count rows yourself to fill one in. `customer_ids` narrows the read to those customers (company ids, at most 20). It matches each company id exactly, and one customer can exist as several company rows (aliases), so pass every company id that names the customer or the figure leaves out the invoices filed under the others. Omit it for every customer. `partial: true` means the aggregate was cut short and every figure is a FLOOR. When `success` is false the read failed: the empty `currencies` is not a measured zero. When the token authorizes one workspace, call this directly — no workspace call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.