Invoice Line Items

Reference for the invoice_line_items resource. Requests follow the conventions in Requests and Responses; fields you receive and may write are filtered by your user's permissions, so responses can contain a subset of the fields below.

Operations

Required on create: link invoice, invoice_billable_item under data.relationships — a create that omits it is rejected with 422 naming the relationship.

How it works

invoice_line_items are the individual charge lines on a customer_invoices header. The invoice header carries no amounts of its own — its total is the sum of its line items — so you create the header first, then add line items to it. Full CRUD plus a list endpoint.

A line item belongs to an invoice through invoice_id, and its permission location is that invoice's customer's location: everything is gated by the Customer Invoices permission at the customer's location (leads use the lead-invoices permission).

Creating

POST /invoice_line_items requires two parents in data.relationships — the invoice it belongs to and the invoice_billable_item (the catalog item that supplies the code/description) — plus these attributes:

curl -X POST "https://portal.securitytrax.com/acme/user/v4/invoice_line_items" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"quantity":"2","unit_price":"10.00","sales_tax_rate":"6.5"},"relationships":{"invoice":{"data":{"type":"customer_invoices","id":100}},"invoice_billable_item":{"data":{"type":"invoice_billable_items","id":5}}}}}'

Computed amounts (read-only)

The money columns are derived from your inputs and returned read-only — a PATCH/POST that sets them returns 422:

• gross_amount = quantity × unit_price
• sales_tax_amount = gross_amount × (sales_tax_rate / 100)
• total_amount = gross_amount + sales_tax_amount

Send only quantity, unit_price, and sales_tax_rate; the amounts are computed on save. On a PATCH that changes any of those three inputs, all three amounts are recomputed — you never send them yourself. (The v1/v3 API instead requires you to send amounts that match; v4 computes them for you.)

billable_item_code and billable_item_description are copied from the linked invoice_billable_item on create and are read-only thereafter. combo_id and status are model-managed.

Updating

PATCH /invoice_line_items/{id} accepts quantity, unit_price, sales_tax_rate, description, and sort. Changing quantity, unit_price, or sales_tax_rate recomputes gross_amount, sales_tax_amount, and total_amount automatically.

Deleting

DELETE /invoice_line_items/{id} soft-deletes the line. Afterward every read of that line returns 404. The parent invoice header is unaffected (its remaining lines still sum to its total).

Listing

GET /invoice_line_items returns non-deleted lines at locations where you can view customer invoices. Filters (all optional, combinable):

Sortable: id, invoice_id, sort, created_at, updated_at. Add ?count_only=true to get just the total without the rows.

Fields

Fields are grouped by the permission that gates them. A group you may not view is absent from responses; a group you may not write is rejected with 422 when sent in a write.

Line Item

View: customers — Customer Invoices at the record's location; leads — Lead Invoices. Create: customers — Customer Invoices at the record's location; leads — Lead Invoices. Update: customers — Customer Invoices at the record's location; leads — Lead Invoices.

Amounts

View: customers — Customer Invoices at the record's location; leads — Lead Invoices.

Managed

View: customers — Customer Invoices at the record's location; leads — Lead Invoices.

Pagination

The list endpoint uses client-controlled offset pagination: ?page= (1-based) and ?per_page= (default 25, max 100). The response mirrors meta.pagination (page, per_page, total, last_page) and sends an RFC5988 Link header; follow rel="next" to walk pages. See Pagination.

Filters

The list endpoint accepts these query-param filters: invoice_id, invoice_billable_item_id, created_at_from, created_at_to, updated_at_from, updated_at_to. An unsupported filter parameter returns 422. See Filtering collections for matching semantics.

Sorting

GET .../invoice_line_items?sort= orders the list by: id, invoice_id, sort, created_at, updated_at. Prefix a field with - for descending; comma-separate for tie-breakers. An unsupported field returns 422. See Sorting collections.

Related

• Requests and Responses — envelope, errors, pagination, and rate limits.
• Authentication — tokens and the Authorization header.