Line Items API
Add, update, duplicate, reorder, and copy invoice line items with server-recalculated totals.
Line-item operations update the invoice composition. They always return recalculated invoice totals. JSON request fields use numbers for quantity, price, and tax inputs. Mutation response totals use decimal strings.
/v1/receivables/line-itemsEndpoints and Schemas
| Method | Path | Request schema | Success response |
|---|---|---|---|
POST | /invoice/{invoiceId} | AddLineItemRequest | LineItemMutationResponse |
POST | /invoice/{invoiceId}/bulk | BulkAddLineItemsRequest | BulkAddLineItemsResponse |
PATCH | /{id} | UpdateLineItemBody | LineItemMutationResponse |
DELETE | /{id} | DeleteLineItemRequest | DeleteLineItemResponse |
POST | /{id}/duplicate | DuplicateLineItemRequest | DuplicateLineItemResponse |
POST | /invoice/{invoiceId}/reorder | ReorderLineItemsRequest | ReorderLineItemsResponse |
POST | /invoice/{invoiceId}/copy-from-product | CopyFromProductRequest | CopyFromProductResponse |
POST | /invoice/{invoiceId}/copy-from-invoice | CopyFromInvoiceRequest | CopyFromInvoiceResponse |
Line Item Input
| Field | Type | Needed | Constraints |
|---|---|---|---|
name | string | yes | 1–500 characters. |
description | string | no | Maximum 2,000 characters. |
quantity | number | yes | Must be zero or greater. |
price | number | yes | Unit price for one item. |
unitPrice | number | no | Legacy alias; use price for new integrations. |
unit | string | no | Maximum 50 characters, such as hour or project. |
taxRate | number | no | Percentage from 0 through 100. |
vat | number | no | Explicit VAT amount override. |
tax | number | no | Explicit tax amount override. |
productId | UUID string | no | Links the item to a catalog entry for usage tracking. |
To create one item, put it in item:
{
"item": {
"name": "Implementation services",
"description": "Phase one delivery",
"quantity": 10,
"price": 150,
"unit": "hour",
"taxRate": 8.5
}
}Bulk creation accepts items with 1–50 entries and applies them in one transaction.
Update and Ownership
PATCH /{id} needs both the parent invoiceId and an updates object. The request changes only the fields inside updates. Delete and duplicate requests also need invoiceId in the JSON body. The server uses it to check that the line item belongs to that invoice and organization.
Response Contract
LineItemMutationResponse.data contains:
success- the created or updated
itemwhen applicable invoiceIdnewSubtotalas a decimal stringnewAmountas a decimal string
Use the returned totals. Do not calculate tax or round values in the client. After any mutation, refresh invoice detail, PDF preview, payment balance, and related analytics.
Reorder and Copy
The reorder request accepts the complete ordered itemIds array for the invoice. Copy-from-product accepts productId and optional quantity (default 1). Copy-from-invoice accepts sourceInvoiceId. The source and destination invoices must be accessible in the same organization.