> ## Documentation Index > Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt > Use this file to discover all available pages before exploring further. # Invoice Item > InvoiceItem represents a single line item on an invoice โ€” a discrete charge for a product or service with its own quantity, price, tax, and period metadata InvoiceItem represents a single line item on an invoice โ€” a discrete charge for a product or service with its own quantity, price, tax, and period metadata. It belongs exclusively to one Invoice via a mandatory many-to-one relation. Key associations are: Invoice (parent document), LedgerAccount (accounting chart of accounts classification), TaxRate (the well-catalog tax rate that was applied), and Media (an optional supporting document such as an image or receipt). The accounting\_classification JSONB field carries the AI-produced Well-taxonomy posting intent used by the journal-entry builder to classify the line for double-entry accounting. | Naming | Value | | ------------------------------- | ------------------- | | Object | Invoice Item | | Resource type (JSON:API `type`) | `invoice_item` | | Collection / records root | `invoice_items` | | REST base | `/v1/invoice-items` | | Entity class | `InvoiceItem` | ## API operations | Operation | Method & path | Status | | --------- | ------------------------------- | ------------- | | List | `GET /v1/invoice-items` | โœ… Implemented | | Retrieve | `GET /v1/invoice-items/{id}` | โœ… Implemented | | Create | `POST /v1/invoice-items` | ๐ŸŸก Planned | | Update | `PATCH /v1/invoice-items/{id}` | ๐ŸŸก Planned | | Delete | `DELETE /v1/invoice-items/{id}` | ๐ŸŸก Planned | ## Data model ### Attributes | Field | Type | Required | Constraints | Allowed values | Description | | -------------------------- | ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | invoice\_item\_id | string, UUID | โœ… Yes | unique; generated by gen\_random\_uuid() at creation | โ€” | Public stable identifier for this invoice line item. Used in all API surfaces and references. | | line\_id | string | โœ… Yes | max length 50; table-wide composite-unique with invoice (no two lines โ€” active or deleted โ€” on the same invoice share a line\_id) | โ€” | Provider-assigned or pipeline-generated identifier for this line within the parent invoice. Used to deduplicate re-ingested lines. The unique constraint is not partial: a soft-deleted line\_id blocks reuse on the same invoice until the row is hard-deleted. | | sku | string | โšช No | max length 100 | โ€” | Stock-keeping unit or product code from the originating system (ERP, e-commerce, MCP connector). | | name | string | โœ… Yes | max length 255 | โ€” | Human-readable label for the line item. Mapped directly from the originating document's line description. | | description | string | โšช No | max length 1000 | โ€” | Extended free-text description of the line item, supplying additional context beyond the name. | | unit\_price | decimal(15,2) | โœ… Yes | CHECK unit\_price >= 0 | โ€” | Price per unit in the invoice's currency, before any discount or tax. Always non-negative. | | currency | string, enum (CurrencyCodeEnum) | โœ… Yes | PostgreSQL native enum currency\_code\_enum | ISO 4217 three-letter codes, e.g. USD, EUR, GBP, JPY, CHF, CAD, AUD, โ€ฆ | Currency of unit\_price, line\_total, tax\_amount, discount, and quantity-derived amounts on this line. | | unit | string, enum (InvoiceLineUnitEnum) | โšช No | PostgreSQL native enum invoice\_line\_unit\_enum; nullable | EA, PC, SET, PR, DZ, C62, MIL, KT, PK, BX, HUR, MIN, SEC, DAY, WEE, MON, ANN, QT, KGM, GRM, TNE, LBR, ONZ, CWT, STN, LTN, MTR, CMT, MMT, KMT, INH, FOT, YRD, SMI, MTK, CMK, INK, FTK, YDK, ACR, HAR, LTR, MLT, MTQ, CMQ, INQ, FTQ, YDQ, GAL, PT, BYT, KBY, MBY, GBY, TBY, BIT, KBI, MBI, GBI, KWH, MWH, WHR, KWT, MWT, BTU, CAL, CEL, FAH, KEL, BAR, PSI, PAL, SRV, LIC, USR, SES, TXN, REQ, PAG, VIS, CLI, IMP, PTC, BPS, SHR, LOT, PNT, TOL, MOL, PPM, PPB, PH, UNT, OTH, NA | UN/CEFACT unit-of-measure code for the quantity on this line. Covers physical quantities, time, data, and service units. | | quantity | decimal(15,2) | โšช No | CHECK quantity >= 0; nullable | โ€” | Number of units. Stored as decimal(15,2) to accommodate fractional service quantities. Populated by the pipeline ingestion from connector data. | | min\_quantity | decimal(15,2) | โšช No | CHECK min\_quantity >= 0; nullable | โ€” | Minimum purchasable quantity for this line, used when the invoice carries tiered or min/max quantity brackets. | | max\_quantity | decimal(15,2) | โšช No | CHECK max\_quantity >= min\_quantity; nullable | โ€” | Maximum purchasable quantity for this line. Must be >= min\_quantity when both are present. | | line\_total | decimal(15,2) | โšช No | CHECK line\_total >= 0; nullable | โ€” | Total amount for this line (unit\_price ร— quantity โˆ’ discount), excl. tax. Populated by the pipeline; may differ from a client-computed product when rounding rules apply. | | discount | decimal(15,2) | โšช No | CHECK discount >= 0; nullable; default 0 | โ€” | Discount amount applied to this line, expressed as an absolute monetary value in the line's currency. Always non-negative. | | tax\_rate | decimal(5,2) | โšช No | CHECK tax\_rate >= 0 AND tax\_rate \<= 100; nullable | 0.00 โ€“ 100.00 | Percentage rate of tax applied to this line, e.g. 20.00 for 20% VAT. Distinct from the applied\_tax\_rate relationship which links to the well-catalog tax rate entry. | | tax\_category | string, enum (TaxCategoryEnum) | โšช No | PostgreSQL native enum tax\_category\_enum; nullable | standard, reduced, super\_reduced, zero\_rated, exempt, reverse\_charge, out\_of\_scope, government, municipal, regulatory, statutory, administrative, medical\_exempt, medical\_reduced, medical\_standard, pharmaceutical, hospital, dental, veterinary, education\_exempt, education\_reduced, books, cultural, research, library, food\_basic, food\_standard, food\_luxury, beverages\_non\_alcoholic, beverages\_alcoholic, restaurant, catering, property\_residential, property\_commercial, construction\_new, construction\_renovation, land, property\_management, transport\_public, transport\_passenger, transport\_freight, vehicle\_sales, vehicle\_parts, fuel, parking, utilities\_domestic, utilities\_commercial, water, sewage, waste\_management, telecommunications, energy\_renewable, financial\_exempt, insurance\_exempt, investment, banking, credit, foreign\_exchange, software\_license, software\_saas, digital\_services, cloud\_computing, data\_processing, telecommunications\_digital, electronic\_delivery, manufacturing, industrial\_equipment, raw\_materials, chemicals, mining, agriculture, forestry, entertainment, sports, gambling, tourism, hospitality, recreation, export, import, intrastat, customs, free\_trade\_zone, diplomatic, legal\_services, accounting, consulting, professional, notary, mixed\_rate, threshold\_based, seasonal, promotional, margin\_scheme, reverse\_auction, unknown, pending, other, not\_applicable | Semantic classification of the tax treatment on this line, aligned to EU/global tax-code taxonomy. | | tax\_scheme | string, enum (TaxSchemeEnum) | โšช No | PostgreSQL native enum tax\_scheme\_enum; nullable | VAT, EU\_VAT, UK\_VAT, MOSS\_VAT, OSS\_VAT, IOSS\_VAT, GST, AU\_GST, CA\_GST, CA\_HST, CA\_PST, CA\_QST, IN\_GST, IN\_CGST, IN\_SGST, IN\_IGST, IN\_UTGST, SG\_GST, MY\_GST, MY\_SST, NZ\_GST, SALES\_TAX, US\_STATE\_TAX, US\_LOCAL\_TAX, US\_USE\_TAX, CA\_RETAIL\_TAX, NY\_SALES\_TAX, TX\_SALES\_TAX, JCT, KR\_VAT, CN\_VAT, RU\_VAT, BR\_ICMS, BR\_IPI, BR\_PIS\_COFINS, MX\_IVA, AR\_IVA, CL\_IVA, EXCISE\_TAX, LUXURY\_TAX, SIN\_TAX, CARBON\_TAX, FUEL\_TAX, TOBACCO\_TAX, ALCOHOL\_TAX, DIGITAL\_TAX, CORPORATE\_TAX, WITHHOLDING\_TAX, BRANCH\_PROFITS\_TAX, TURNOVER\_TAX, GROSS\_RECEIPTS\_TAX, CUSTOMS\_DUTY, IMPORT\_DUTY, EXPORT\_DUTY, ANTI\_DUMPING\_DUTY, COUNTERVAILING\_DUTY, TARIFF, PROPERTY\_TAX, TRANSFER\_TAX, STAMP\_DUTY, INHERITANCE\_TAX, GIFT\_TAX, WEALTH\_TAX, PAYROLL\_TAX, SOCIAL\_SECURITY\_TAX, UNEMPLOYMENT\_TAX, DISABILITY\_TAX, MEDICARE\_TAX, MUNICIPAL\_TAX, CITY\_TAX, COUNTY\_TAX, DISTRICT\_TAX, TOURIST\_TAX, OCCUPANCY\_TAX, FINANCIAL\_TRANSACTION\_TAX, BANK\_TAX, INSURANCE\_PREMIUM\_TAX, TELECOM\_TAX, UTILITY\_TAX, AVIATION\_TAX, SHIPPING\_TAX, ENVIRONMENTAL\_TAX, PLASTIC\_TAX, PACKAGING\_TAX, WASTE\_TAX, CONGESTION\_TAX, OTHER, MIXED, UNKNOWN, NONE, PENDING | The tax framework under which the line is taxed, e.g. EU\_VAT, GST, US\_STATE\_TAX. Covers 90+ global tax schemes. | | tax\_amount | decimal(15,2) | โšช No | CHECK tax\_amount >= 0; nullable | โ€” | Absolute tax amount for this line in the line's currency, derived from unit\_price ร— quantity ร— tax\_rate / 100. | | accounting\_unit\_price | decimal(15,2) | โšช No | nullable | โ€” | Unit price converted to the workspace's functional accounting currency. Set by the FX-matching pipeline when the invoice currency differs from the workspace currency. | | accounting\_line\_total | decimal(15,2) | โšช No | nullable | โ€” | Line total converted to the workspace's functional accounting currency. Parallel to accounting\_unit\_price for full multi-currency double-entry support. | | period\_start | timestamp | โšช No | nullable | โ€” | Start of the service period covered by this line item. Used for subscription, retainer, and recurring-service invoices. | | period\_end | timestamp | โšช No | nullable | โ€” | End of the service period covered by this line item. Paired with period\_start for accrual accounting period allocation. | | accounting\_classification | jsonb | โšช No | nullable; partial functional index on (accounting\_classification->>'status') WHERE deleted\_at IS NULL (idx\_invoice\_items\_accounting\_classification\_status โ€” defined in Migration20260525101000 only, not expressible via MikroORM decorators) | \{ status: 'ready', wellCoaVersion: string, intent: WellPostingIntent, rawFacts: InvoiceItemAccountingLLMFacts } \| \{ status: 'needs\_review', wellCoaVersion: string, reason: InvoiceItemAccountingReviewReason, rawFacts?: ..., details?: string } | AI-produced Well-taxonomy accounting classification for this line. Written by the journal-entry draft builder. status='ready' means a valid WellPostingIntent was resolved and the line can be posted to the ledger. status='needs\_review' carries a reason code (missing\_accounting\_facts, llm\_requested\_review, unknown\_semantic\_role, unsupported\_invoice\_item\_posting\_kind, unsupported\_invoice\_item\_transfer\_role, invalid\_accounting\_qualifier, posting\_intent\_halt) and blocks automatic posting. | | created\_at | timestamp, ๐Ÿ”’ system | โœ… Yes | set once on insert via onCreate lifecycle hook | โ€” | ISO 8601 timestamp recording when the invoice item row was first persisted. | | updated\_at | timestamp, ๐Ÿ”’ system | โšช No | set on insert and refreshed on every update via onCreate/onUpdate lifecycle hooks | โ€” | ISO 8601 timestamp of the most recent write to this row. | | deleted\_at | timestamp | โšช No | nullable; soft-delete sentinel; partial indexes exclude rows where deleted\_at IS NOT NULL | โ€” | When set, marks this line as logically deleted. All active-record queries filter deleted\_at IS NULL. Cleared only by an explicit restore operation. | ### Relationships | Name | Type | Required | Description | | ------------------ | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | invoice | to-one (invoice) | โœ… Yes | The parent invoice to which this line belongs. Non-nullable ManyToOne to the Invoice entity. A line cannot exist without its parent. Indexed via idx\_invoice\_items\_invoice\_deleted (invoice + deleted\_at) and the partial index idx\_invoice\_items\_invoice\_active (invoice\_pk WHERE deleted\_at IS NULL) for hot UPDATE paths during invoice-merge operations. | | ledger\_account | to-one (ledger\_account) | โšช No | Optional link to the LedgerAccount (chart-of-accounts entry) that this line item has been assigned to. Set by the accounting classification pipeline or by a user override. Indexed via idx\_invoice\_items\_ledger\_account. | | applied\_tax\_rate | to-one (tax\_rate) | โšช No | Optional link to the Well-catalog TaxRate entry that was applied when computing the tax on this line. Distinct from the scalar tax\_rate column which stores the raw percentage. Indexed via idx\_invoice\_items\_applied\_tax\_rate. | | media | to-one (media) | โšช No | Optional supporting document or image attached to this line (e.g. a product image, receipt scan, or delivery note). ManyToOne to the Media entity. Indexed via idx\_invoice\_items\_media. | ### System-computed * invoice\_item\_id is generated by PostgreSQL gen\_random\_uuid() at insert time and is immutable thereafter. * created\_at is set once by the MikroORM onCreate lifecycle hook; it is never updated. * updated\_at is set by both onCreate and onUpdate hooks โ€” it reflects the wall-clock time of the most recent write. * deleted\_at is null on creation. Setting it to a non-null timestamp constitutes a soft delete. The partial indexes idx\_invoice\_items\_invoice\_active and idx\_invoice\_items\_accounting\_classification\_status both carry WHERE deleted\_at IS NULL to exclude deleted rows from hot read paths. * The composite unique constraint (invoice, line\_id) is table-wide (not partial): it enforces that no two lines โ€” active or soft-deleted โ€” on the same invoice share the same line\_id. A soft-deleted line\_id cannot be reused for a new line on the same invoice without first hard-deleting the old row. * accounting\_unit\_price and accounting\_line\_total are derived by the FX-matching pipeline (invoice.service.ts + fx-rate.service.ts) when the line currency differs from the workspace's functional currency. They are never computed by the API layer on a write request. * accounting\_classification is written exclusively by the invoice-journal-entry-draft builder (services/accounting/invoice-journal-entry-draft.builder.ts) and classifyInvoiceItemAccounting(). It is never set by a direct API mutation. Its status field is indexed via a JSONB functional partial index (migration-only; MikroORM decorators cannot express JSONB key expressions or partial predicates, so schema:fresh diverges from production on this index). * discount defaults to 0 at the database level when not supplied by the connector. ## Example ```json theme={null} { "data": { "type": "invoice_item", "id": "a3f7b2c1-84d9-4e10-b6e0-2f1d5c839740", "attributes": { "invoice_item_id": "a3f7b2c1-84d9-4e10-b6e0-2f1d5c839740", "line_id": "line-001", "sku": "SVC-CONSULTING-2026", "name": "Strategic consulting โ€” Q2 2026", "description": "Monthly advisory retainer covering financial modelling and board prep.", "unit_price": "4500.00", "currency": "EUR", "unit": "MON", "quantity": "1.00", "min_quantity": null, "max_quantity": null, "line_total": "4500.00", "discount": "0.00", "tax_rate": "20.00", "tax_category": "standard", "tax_scheme": "EU_VAT", "tax_amount": "900.00", "accounting_unit_price": "4500.00", "accounting_line_total": "4500.00", "period_start": "2026-04-01T00:00:00.000Z", "period_end": "2026-06-30T23:59:59.000Z", "accounting_classification": { "status": "ready", "wellCoaVersion": "1.0.0", "intent": { "semanticRole": "operating_expense", "postingKind": "invoice_accrual", "documentPolarity": "purchase", "wellCoaVersion": "1.0.0" }, "rawFacts": { "well_semantic_role": "operating_expense", "posting_kind": "invoice_accrual", "document_polarity": "purchase", "tax_behavior": "exclusive", "confidence": 0.94, "classifier_model": "claude-opus-4-6" } }, "created_at": "2026-04-30T09:14:22.000Z", "updated_at": "2026-05-02T11:07:55.000Z", "deleted_at": null }, "relationships": { "invoice": { "data": { "type": "invoice", "id": "d8e1f4a2-3c7b-4b85-9e2d-6a0f7c1e4821" } }, "ledger_account": { "data": { "type": "ledger_account", "id": "f1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" } }, "applied_tax_rate": { "data": { "type": "tax_rate", "id": "b9c8d7e6-f5a4-3b2c-1d0e-9f8e7d6c5b4a" } }, "media": { "data": null } } } } ``` Source: `apps/api/src/database/entities/InvoiceItem.ts` ยท domain: financial-graph ยท tier: Supporting