Sum missing invoices of a week or months
well_sum_missing_invoicesThe missing supplier invoices of one ISO week, or of up to 3 calendar months, as one total: how many suppliers still miss an invoice, how many transactions they cover, and the spend they cover, in the currency of the lines and converted to the workspace base currency. It returns no rows.
week is an ISO week, YYYY-Www (Monday to Sunday), for example 2026-W40. A week has ended when its Sunday has ended in the workspace time zone. Omit it to read the last week that has ended. A refusal carries error_code: week_invalid for a week its year does not have (a week 53 in a 52-week year), week_not_ended for a week that has not ended yet, no_workspace when no workspace is in context, read_failed when the read of the week failed.
Pass from_month (and to_month, both YYYY-MM) instead of week to sum whole calendar months: from_month alone reads one month, both read every month from the first to the last, at most 3 months. A month has ended when its last day has ended in the workspace time zone. With through_today: true the last month may be the running one, read up to today with is_complete: false. A month that starts after today is refused with month_not_started, and a running month without through_today with month_not_ended. A month read that takes longer than its time budget is refused with read_timed_out: the workspace was not read. A to_month before from_month, or months passed beside week is refused with months_invalid, and more than 3 months with months_too_many. A month read returns from_month and to_month in place of week, and no pending_count.
Pass through_today: true to read the week that is running: with week omitted it reads the current ISO week, and a named week that has started reads from its Monday to today in the workspace time zone. is_complete is false for that open window, so the figures cover the days so far and never compare to a full week. A week that starts after today is still refused with week_not_ended. Without through_today, a week that has not ended is refused.
supplier_count counts the suppliers that still miss an invoice, with the gaps and the row rule of the missing-invoices card; over several months a supplier counts once. transaction_count counts the transactions of those suppliers that still miss an invoice. total is the spend those suppliers cover, converted to currency (the workspace base currency). It is null when a line has no exchange rate for its date, or when the amount of a line held out as a possible duplicate is unknown because the read's sample does not carry it: a partial sum would read as the whole figure. It covers the named suppliers' groups only, so it is not the conversion of a net below, which also holds the groups with no named supplier.
totals_by_currency is the money of the week still missing an invoice, ONE set per currency in the lines' own currency (the currency the bank lines are in), in major units: gross, the copies and own_company movements it holds, and net, the figure to quote. Never add two sets, and never convert one. It is null when the figures could not be read. totals_unreadable_count counts the lines with no readable amount, which sit in no figure.
possible_duplicates holds the money of the bank lines that are half of a pair Well cannot tell apart (two lines of the same amount to the same supplier on the same day): the second line of such a pair is left out of net until the person says both are real payments, so net counts that money once. possible_duplicate_pairs lists those pairs, one line each: the supplier, the amount of ONE of the two lines, the two days, the two movement ids and the namespace its answer is saved under. Show one line per pair and ask the person once: are both lines real payments (keep) or does the second one repeat the first (drop)? Record each answer on its own with well_upsert_preference: key missing_invoice_duplicate_verdicts, scope workspace, the pair's namespace as namespace, value { "decision": "keep" | "drop" }. A keep puts the second line back in the total, a drop keeps it out, and either way the pair is never asked again. Never decide the answer yourself. A run with nobody present asks nothing and stores nothing: it names the held amount in its one line.
bank_connected is true when the workspace has a bank feed connected: synced, syncing, or in error. It is false when no bank feed is connected, or every one is disabled or not set up. Only a live bank feed counts: a workspace with imported bank statements only reads false too. Then Well sees no bank spend for the week, so its figures cannot say that nothing is missing: the week could not be checked.
largest_suppliers names the 3 suppliers of supplier_count with the most spend still missing an invoice, biggest first, a supplier with no figure last: each with its name, its tx_count, its base_total_amount in currency, without a line held out as a possible duplicate (null when a line has no exchange rate, or when the amount of a held line is unknown) and its available_routes, the order to look for its invoices in, as on the rows of well_list_missing_invoices (mail_search when the caller's own Gmail is connected). other_supplier_count counts the suppliers of supplier_count it leaves out, and other_suppliers_total is their spend in currency, summed by Well. other_suppliers_total is null when no supplier is left out, when one of them has no figure, or when candidates_truncated is true: then quote the count alone. Never compute it from total, and never from totals_by_currency.
pending_count counts the transactions of those suppliers whose candidate invoice already waits for a confirmation. They are in supplier_count and total, as on the card. unattributed_group_count counts the groups of spend with no named supplier, and unattributed_transaction_count the transactions those groups hold. They are not in supplier_count, transaction_count or total, and they are in totals_by_currency. candidates_truncated: true means the scan filled its page, so supplier_count, total and pending_count are floors; totals_by_currency is read apart and still covers every line.
This tool reads the user's data and changes none of it.
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 |
|---|---|---|---|
| week | No | ISO week, YYYY-Www (Monday to Sunday). It must have ended, unless `through_today` is true. Omit it for the last ended week, or for the running week with `through_today`. Never with `from_month`. | |
| to_month | No | Last calendar month to sum, YYYY-MM, at most 3 months after `from_month` counted inclusive. Needs `from_month`. | |
| from_month | No | First calendar month to sum, YYYY-MM. Alone it reads that one month. Never with `week`. | |
| 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. | |
| through_today | No | Read the running week, or a running last month, up to today. Set it to true for "this week" or for months that end with the current one; false reads like absent. The result has `is_complete: false` while the window runs. | |
| 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 |
|---|---|---|---|
| to | No | Last day of the window, YYYY-MM-DD, inclusive: the Sunday, the last day of `to_month`, or today for a running week or month read through today. | |
| from | No | First day read, YYYY-MM-DD: the Monday of the week, or the first day of `from_month`. | |
| week | No | ||
| error | No | ||
| total | No | The named suppliers' groups only, in the base currency, without a line held out as a possible duplicate. Null when a line has no exchange rate, or when the amount of a held line is unknown because the read's sample does not carry it. | |
| success | Yes | ||
| currency | No | The workspace base currency (ISO 4217) `total` is converted to. Write `total` with its symbol or code, never the currency of the person's language. | |
| to_month | No | Last month read, YYYY-MM. Present on a month read only. | |
| error_code | No | ||
| from_month | No | First month read, YYYY-MM. Present on a month read only. | |
| is_complete | No | False when the window ends today and has not ended: the figures cover the days so far. | |
| workspace_id | No | ||
| pending_count | No | Absent on a month read. | |
| bank_connected | No | True when a bank feed is connected (synced, syncing or in error). False means the week could not be checked. | |
| supplier_count | No | ||
| 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. | |
| largest_suppliers | No | The 3 suppliers with the most spend still missing an invoice, biggest first. | |
| transaction_count | No | The transactions of the counted suppliers that still miss an invoice. | |
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| totals_by_currency | No | The week's money still missing an invoice, one set per currency in the lines' own currency. Null when unreadable. | |
| candidates_truncated | No | ||
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| other_supplier_count | No | The suppliers of `supplier_count` that `largest_suppliers` leaves out. | |
| other_suppliers_total | No | The spend of the suppliers `largest_suppliers` leaves out, in `currency`, summed by Well. Null when none is left out, one has no figure, or the read was cut. | |
| 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. | |
| totals_unreadable_count | No | Lines with no readable amount, in no figure of `totals_by_currency`. Null with it. | |
| possible_duplicate_pairs | No | The pairs of bank lines Well cannot tell apart: two lines of the same amount to the same supplier on the same day, with no invoice behind either. The SECOND line of each pair is held out of `net` and sits in `possible_duplicates`, so the total counts the money once. Ask the person whether both lines are real payments (`keep`) or the second one repeats the first (`drop`), and record each answer with `well_upsert_preference` under the key `missing_invoice_duplicate_verdicts`, `scope: "workspace"` and the `namespace` of the pair, value `{ "decision": "keep" | "drop" }`: a `keep` puts the line back in the total, a `drop` keeps it out, and either way the pair is never asked again. Empty when the read found no such pair. | |
| unattributed_group_count | No | ||
| unattributed_transaction_count | No | The transactions of the groups with no named supplier, which are not in `transaction_count`. | |
| possible_duplicates_unavailable | No | True when the possible-duplicate check could not run, or its pair list was cut at its cap: some pairs may be missing from `total` and `possible_duplicate_pairs`. Say in one plain line that possible duplicates could not be checked, then quote the figures as they come. |