Record a claim
well_record_claimRecord a claim: start following a refund the person asked a supplier for, one task per supplier credit note. The task keeps the credit note, the supplier, the amount and the day the refund is expected, shows in the person's task list and turns red when that day passes. It closes by itself when a confirmed payment covers the credit note. It writes only inside Well and sends nothing to anyone.
Call it on the workspace that holds the credit notes, with the credit_note_ids (one to 10 invoice ids of supplier credit notes) and expected_by, the day the refund is expected (YYYY-MM-DD, from today to 180 days ahead). Well copies the amount, the currency and the supplier from each credit note: the call carries none of them.
Call it only after the send call for the same credit notes returned success: true, or returned an approval_url for the person to approve. Never call it for a claim the person declined, for an email shown as text only, for a credit note you could not prove is owed, or on your own guess.
Read claims, one item per credit note, with outcome:
recorded: the task is written (claim: the task id, the supplier, the amount, the currency, the day the refund is expected, the status).already_recorded: this credit note already has a live claim (claim); nothing was written.refused: nothing was written.reasonsays why:credit_note_not_found(no such invoice in this workspace),not_a_credit_note(the document is not a credit note),not_a_supplier_credit_note(the credit note is not proved to be on the company's purchase side: it is a sale, both legs are the company's own, neither is, or the receiver is missing or not proved to be the company),duplicate(the credit note is a folded duplicate; claim the document it was folded into),own_company_unset(no own company of the workspace is established yet, so the side cannot be proved),own_set_incomplete(the workspace's own companies could not all be read, so the side cannot be proved now),supplier_unknown(the credit note names no supplier),amount_unknown(the credit note has no total),already_settled(a confirmed payment already covers it),expected_by_out_of_range(the day is before today or more than 180 days ahead).
A refund watch after a return or a cancellation. When no credit note exists yet, because the person returned an item or cancelled a service on a merchant's site with a browser task, pass refund_watch in place of credit_note_ids and expected_by: the browser task (browser_task_id), the merchant as a company of the workspace (merchant_company_id), the refund the site stated (expected_amount, currency) and the day it is expected (expected_by). One watch per browser task. Call it only after the person said yes to the watch. Read refund_watch: outcome recorded, already_recorded (the live watch is returned) or refused with reason browser_task_not_found, merchant_not_found, amount_invalid or expected_by_out_of_range. The watch itself sends nothing; its scheduled run reads it with well_get_task and changes it with well_update_refund_watch.
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 |
|---|---|---|---|
| expected_by | No | The day the refund is expected, YYYY-MM-DD, from today to 180 days ahead. | |
| refund_watch | No | A refund watch after a return or a cancellation, in place of credit_note_ids and expected_by. | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say 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. | |
| credit_note_ids | No | The supplier credit notes of the claim email, as invoice ids in the workspace of this call. | |
| idempotency_key | No | Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation. | |
| 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 |
|---|---|---|---|
| error | No | ||
| claims | No | ||
| success | Yes | ||
| refund_watch | 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. | |
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| 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. |