Define line items
well_define_line_itemsRead what this workspace has already billed, and flag which of the lines the user just described equal a past line. Use it before well_create_invoice_from_data, when the invoice's lines come from the user's words ("two days of consulting, and the hosting").
Never call it to add a product or a service to the catalog, or to change a product's price ("Ajoute le produit Audit SEO à 1 200 € HT", "Passe Audit SEO à 1 400 €"): those are well_create_product and well_update_product, and they bill nothing.
Pass lines: one entry per line the user described, each with a line_key (a fresh UUID you choose for that line and keep for the whole conversation, never its position in the list), its name, its sku when the user gave one, and its quantity and tax_rate when the user stated them ("3 days at 600" is quantity 3, unit_price 600; tax_rate is a percentage, 20 for 20%). Pass product_id for the exact live product selected by the skill from well_list_products, or for a product in this tool's catalogue whose SKU exactly equals the line's SKU. For a selected catalogue product, pass its unit_price explicitly when its currency is the invoice currency; a product id links the line but does not select or supply its price. A name never selects a catalogue product. Pass unit_price only for the resolved price of the line; never invent a figure. unit_price is in currency, the invoice's: a price the user stated in another currency ("50€ a day" on an AED invoice) is converted first with well_get_fx_quote (base the price's currency, quote the invoice currency, amount the unit price), and its converted_amount is passed as unit_price. Never leave such a price out unless the rate tool returns no_rate, never pass it unconverted, and never convert it yourself. Pass customer_id (the entity_id of the pre-selected or chosen customer) when you know the customer, so the lines already billed to them rank first, and customer_kind: "person" when that customer is a private individual. Pass currency (the invoice's ISO 4217 code, e.g. "EUR") when you know it, so only past lines billed in that currency come back and match: a price billed in another currency does not hold.
Returns items: the workspace's distinct past sales lines (one product billed in two currencies is two items), newest first (customer's own lines ahead of the rest), each with item_id, name, sku, product_id, unit_price, currency, tax_rate, times_billed (counted inside the recent window, not a lifetime total), last_billed and billed_to_customer. Returns matches: one entry per sent line, matched_on "sku" or "name" with the item_id of the past line it equals, or both null when no past line equals it, plus requested: the quantity, unit_price and tax_rate you sent for that line, echoed unchanged (null for a figure you did not send). A catalogue line's product_id from well_list_products is checked against live products in this workspace and echoed unchanged. Returns catalogue: the live products whose SKU exactly matches a sent line's SKU, with each product_id, name, sku, unit_price, currency, supply_type and billing_interval. It is empty when no sent SKU matches. A name never selects a catalogue product. Returns totals: items_total, tax_total and grand_total of the lines in requested, computed by Well in currency (each line's total and tax held to the currency's minor units, a line with no quantity counted once, a line with no unit_price and an exact match at the matched past item's unit_price, a line with no tax_rate at the vat_default rate), or null when you passed no currency, a line still has no unit price, or a line has no known tax rate (none stated and a null vat_default.rate). needs_pick is true while a line still has no price: it equals no past line, or equals past lines billed at different prices. When it is false every line has its price and the person has nothing to pick. These are the figures to show the user. NEVER compute a total or a tax yourself, and never send one to a create tool: Well computes them from the lines. Well does not match on the other figures.
Returns customer_last_invoice when you passed customer_id: the newest invoice issued to that customer, company or private individual (never another customer's, never a credit note), with reference_number, issue_date, currency (null when that invoice carries none) and its lines (name, quantity, unit_price, tax_rate), or null when they have none. It is what the person means by "as usual", "the usual fee", "same as last time" or "comme la dernière fois" for this customer: take the line or the rate they refer to from it, name it with its date, and when it is null say this customer has no past invoice.
Returns vat_default: the VAT rate a line assumes when the user stated none, worked out by Well, with its basis (rate in percent, or null when no basis exists). In order: "last_invoice_to_customer" the rate of every line of the newest invoice the issuer sent this customer, named by source_invoice (reference_number, issue_date); "domestic" the issuer's own country's standard rate for a customer in the same country; "intra_eu_reverse_charge" or "intra_eu_no_vat_id" a customer in another EU country, 0; "export" a customer outside the EU, 0; "workspace_default" the workspace's default VAT rate; "issuer_country_standard" the issuer country's standard rate, for a customer whose country is not known yet (a new customer, or none named yet); "unknown" no basis, rate null. The card shows that rate on every line that has none stated, ready to edit. NEVER ask the user for a VAT rate and never type one yourself: pass tax_rate only when the user stated one in their own words, or referred to the rate of their last invoice to this customer ("TVA comme la dernière fois"), which is the tax_rate of customer_last_invoice. A stated rate wins over vat_default. Say the assumed rate and its basis to the user in one line, so one word corrects it.
When the lines belong to a draft already saved (the person changes its lines, quantities or currency), pass its invoice_id and, on each line that is already on the draft, its line_id from the lines of the last invoice answer. Then a figure you did not send is the draft's saved one: requested carries the saved quantity, unit price and tax rate, and when currency differs from the draft's currency the saved prices come converted by Well at the rate of the issue date, with fx_conversion (from_currency, to_currency, rate, rate_display, rate_date, source) naming the rate; show rate_display, the rate with no padding zeros. In Well's chat a call without invoice_id reads the newest draft this conversation created for the same customer the same way. draft_invoice_id names the draft the figures came from, and each match of a saved line carries its line_id. NEVER ask the person for a price the draft already holds, in any currency, and never convert a price yourself. In Well's chat, write the answered lines to the draft with well_update_invoice and its line_items, never a delete and a new create.
A match is exact equality only: the same sku, or the same name once case and spacing are ignored. A null is not proof the line is new. Read items and judge whether a near name is the same thing. Only invoices this workspace issued or was paid for are read, never drafts, canceled invoices or invoices it received. Past invoice prices are historical candidates; the skill decides whether one applies to this line.
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 |
|---|---|---|---|
| limit | No | Max past items returned (default 50). | |
| lines | No | The lines to check against the history. | |
| currency | No | The invoice's ISO 4217 currency. Only past lines in it come back and match. | |
| invoice_id | No | The saved draft these lines belong to. Its saved figures fill what you did not send. | |
| customer_id | No | The customer's entity_id. Their past lines rank first. | |
| 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. | |
| customer_kind | No | The customer's `customer_kind` from well_list_customers: "person" for a private individual. Left out, customer_id names a company. | |
| 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 |
|---|---|---|---|
| error | No | ||
| items | Yes | ||
| totals | No | ||
| matches | Yes | ||
| success | Yes | ||
| catalogue | Yes | ||
| needs_pick | No | ||
| vat_default | No | ||
| error_reason | No | ||
| fx_conversion | 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. | |
| draft_invoice_id | No | ||
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| customer_last_invoice | No | ||
| 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. |