Sum outstanding receivables
well_sum_receivablesWhat 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 or credit note) or a sales order that is a sale (rule.sales_orders), 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. A paid sales order counts, its unpaid rest is owed. A sales order the customer paid in full or in part is a sale, so its balance_due is owed until an invoice bills the order and carries the receivable instead; an unpaid order is no sale yet and owes nothing. While Well is unsure that an order and an invoice are one sale, the customer owes it once, on the paid order. A row read of rule.document_types does not return the orders: the figure is the one to state. 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. connection_states is the stored-status summary of contributing connections; an empty array means none were found, and null means that status read was incomplete. unhealthy_sources keeps known source names, effective states and last-updated dates in structured fields. Do not repeat a state already attached to a named connection. Keep those names and internal state wording out of the member-facing warning. A summary state with no named source remains an unlabelled stored status.
Each currency row's unhealthy_sources lists only connections that supplied one or more invoices in that total and need attention. When source_health_note is set, relay it with the figure; it gives the freshness limitation and a next step. An empty list means no contributing unhealthy source was found. source_health_partial: true means the source-health read was incomplete; do not describe unlisted sources as healthy.
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_countandno_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_countandmarked_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_countanddraft_total(per row): draft invoices with a balance left, at any payment status exceptunknown. A draft atmarked_paidis 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_countandunsettled_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.nullmeans the count failed, which is not0.unattributed_count: outstanding-looking invoices Well could place on neither side. They may be owed to the workspace and are in no figure.nullmeans the count failed, and it is alsonullwhencustomer_idsnarrows 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.nullmeans the count failed.no_balance_count: unpaid or part-paid invoices, drafts included, with nobalance_duerecorded, so no amount to count. In no figure.nullmeans the count failed.no_balance_overdue_count: ofno_balance_count, the issued invoices (never a draft) past their due date onas_of_date(due before that date; one due on it is not yet overdue). On an ask for the overdue or late invoices, this is the no-balance count to state, and an invoice ofno_balance_countnot counted here is not overdue: never list it as late.nullmeans the count failed.outstanding_payment_unknown_count: invoices that ARE counted inoutstandingand 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 notunknown_payment_status_count: that count is a recompute that halted (balance not trusted, in no figure), while this one is counted inoutstandingbut 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.nullmeans the count failed.party_scope: whenparty_scope.side_unknownis 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, exceptoutstanding_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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| customer_ids | No | Company ids of the customers to restrict the figure to. Each id matches exactly, so include every company id that names the same customer, aliases included. Omit for every customer; see the description. | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which. | |
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rule | Yes | ||
| sums | Yes | The four-way own-side partition of the measured set. `proven` cells hold only rows the stored facts prove; `estimated` cells hold the rows a weak claim sides (inside `unattributed`, never inside `proven`); `unattributed` is the unknown remainder with the direction twin's `by_reason` split; `no_currency` counts measured rows with no currency. `available: false` means a cell read failed — a partial block would not add up, so the block is omitted rather than floored. | |
| as_of | Yes | ||
| error | No | ||
| partial | Yes | ||
| success | Yes | ||
| as_of_date | Yes | ||
| currencies | Yes | ||
| party_scope | Yes | What the receivable side resolved to. `side_unknown: true` means the workspace resolved no own company, so NO side filter was applied (`applied: false`) and every figure covers invoices on both sides — say the side is unknown, never that the figure is what customers owe. `null` when no read reported a scope resolution. | |
| completeness | Yes | ||
| customer_ids | Yes | ||
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| no_balance_count | Yes | ||
| no_currency_count | Yes | ||
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| unattributed_count | Yes | ||
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| source_health_partial | Yes | ||
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. | |
| no_balance_overdue_count | Yes | ||
| unknown_payment_status_count | Yes | ||
| outstanding_payment_unknown_count | Yes |