> ## Documentation Index > Fetch the complete documentation index at: https://docs.joinluminous.com/llms.txt > Use this file to discover all available pages before exploring further. # Append line items to a purchase order > Append one or more line items to an existing **active** purchase order without pruning any existing lines. This is the additive counterpart to `PUT /purchase-orders/{id}`, which is replace-all (any omitted line is deleted). The appended lines go through the same builders as `POST /purchase-orders` — unit-of-measure conversion, incoming-stock increment, cost recompute, and lot / custom-field / tag handling are identical to create — and the purchase order header totals (`order_cost`, `order_quantity`, `item_count`, tax/shipping) are recalculated afterward. Only active purchase orders accept new lines; a `409 Conflict` is returned for completed / received / deleted orders. > **Note:** This endpoint is part of the container / Purchase-to-Order workflow and is gated by > the `PURCHASE_TO_ORDER` feature flag. Contact Luminous to have it enabled for your tenant. ## OpenAPI ````yaml /api-reference/build.yaml post /purchase-orders/{purchaseOrderId}/items openapi: 3.0.0 info: title: Luminous API version: 1.0.0 description: API documentation for Luminous servers: - url: https://{companyName}.api.joinluminous.com/external/api/v1 variables: companyName: default: companyName description: Your company-specific subdomain security: [] tags: - name: Products description: Get and manage products - name: Pricing description: Manage price schedules, levels, and customizations - name: BOMs description: Manage Bills of Materials (BOMs) - name: Labels description: Label rendering via Labelary ZPL service - name: Companies description: Manage business accounts and their associated data - name: Contacts description: Manage contact information for individuals - name: Suppliers description: Manage suppliers (factories) — vendors used on purchase orders - name: Supplier SKUs description: Manage per-supplier SKU and unit-cost overrides for products - name: Locations description: Manage warehouses and locations - name: Inventory description: Get and adjust product stock levels - name: Lots description: Create, update, and delete product lots (batches) - name: Transfer Orders description: Manage transfer orders - name: Fulfillment Orders description: Manage fulfillment orders and picklists - name: Fulfillment Priority Lists description: Configure fulfillment routing priority lists - name: Purchase Orders description: Get and modify purchase orders - name: Supplier Portal description: >- Read a supplier's response to a purchase order and control the one-click portal link - name: Receiving Reports description: Manage receiving reports - name: Payment Obligations description: Manage payment obligations for purchase orders - name: Sales Orders description: Manage sales orders and sales order shipments - name: Purgatory description: >- Inspect and resolve non-posted sales orders in the purgatory staging workflow - name: PickFlow Shipping description: >- Provider-agnostic shipping rates, services, packages, and label purchase for PickFlow - name: Cycle Counts description: >- Create, drive, and post PickFlow cycle counts — batches, per-warehouse sessions, and CSV import/export - name: Print Stations description: List paired print stations and enqueue print jobs to them - name: Invoices description: Get and manage invoices - name: Work Orders description: >- Manage work orders — production lifecycle, steps, materials, links, shipments, and comments - name: Production Batches description: Group and manage work orders as production batches - name: Bills description: >- Accounts payable bill management, payments, attachments, allocations, and variance - name: Prepayments description: Manage vendor prepayments and applications - name: Vendor Credits description: Manage vendor credits and applications - name: Vendor Returns description: Manage vendor returns and credit generation - name: Customer Returns description: Manage customer returns (sales returns), receiving, and restock behavior - name: Stock Snapshot description: Point-in-time stock snapshots with export support - name: Consumption description: Consumption reports and exports - name: Inventory Aging description: Cost-layer-based inventory aging reports - name: Bills Reports description: Accounts payable bills aging reports - name: Forecast description: Materialized forecast data - name: Reports description: Close the books, inventory discrepancy, transaction COGS, and EDI reports - name: Tags description: Add/remove tags across various resources - name: Custom Fields description: Get and set custom fields across various resources - name: Currency description: Currency configuration, exchange rates, and conversion - name: Integration Mappings description: Manage integration mappings for external systems - name: Integration Field Mappings description: Manage field-level mappings between Luminous and external systems paths: /purchase-orders/{purchaseOrderId}/items: post: tags: - Purchase Orders summary: Append line items to a purchase order description: > Append one or more line items to an existing **active** purchase order without pruning any existing lines. This is the additive counterpart to `PUT /purchase-orders/{id}`, which is replace-all (any omitted line is deleted). The appended lines go through the same builders as `POST /purchase-orders` — unit-of-measure conversion, incoming-stock increment, cost recompute, and lot / custom-field / tag handling are identical to create — and the purchase order header totals (`order_cost`, `order_quantity`, `item_count`, tax/shipping) are recalculated afterward. Only active purchase orders accept new lines; a `409 Conflict` is returned for completed / received / deleted orders. > **Note:** This endpoint is part of the container / Purchase-to-Order workflow and is gated by > the `PURCHASE_TO_ORDER` feature flag. Contact Luminous to have it enabled for your tenant. operationId: appendPurchaseOrderItems parameters: - in: path name: purchaseOrderId required: true schema: type: integer description: ID of the purchase order to append line items to requestBody: required: true content: application/json: schema: type: object required: - items properties: items: type: array minItems: 1 description: Line items to append to the purchase order items: type: object required: - quantity - unit_price properties: product_id: type: integer nullable: true description: ID of the product (required if `sku` not provided) example: 123 sku: type: string maxLength: 255 nullable: true description: >- SKU of the product (required if `product_id` not provided) example: WIDGET-001 quantity: type: number format: float minimum: 0.001 description: Quantity of the item ordered example: 10.5 unit_price: type: number format: float description: Price per unit example: 49.99 ordered_qty: type: number format: float minimum: 0.001 nullable: true description: >- Ordered quantity in base unit of measure (calculated automatically if not provided) example: 10.5 received_qty: type: number format: float minimum: 0 nullable: true description: Quantity already received example: 0 expected_ship_date: type: string format: date nullable: true description: >- Per-line expected ship date override. When omitted or null, the line inherits the PO header `requested_ship_date`. example: '2026-08-17' expected_arrival_date: type: string format: date nullable: true description: >- Per-line expected arrival date override. When omitted or null, the line inherits the PO header `arrival_due_date`. example: '2026-08-22' lot_id: type: integer nullable: true description: ID of the product lot example: 789 lot_number: type: string nullable: true description: >- Lot number for the item (used when the product has lot tracking enabled) example: LOT-12345 lot_name: type: string nullable: true description: Alias for `lot_number`. uom_id: type: integer nullable: true description: >- ID of the unit of measure for the item. If omitted, a default is resolved automatically in priority order: the product's default purchase unit, then its default selling unit, then the base unit of its unit class, then the account's base unit. If no unit of measure is supplied and no default can be resolved, the request fails with a 422 error. example: 1 source_sku: type: string maxLength: 255 nullable: true description: Source SKU from the supplier example: SUPPLIER-SKU-123 tags: type: array nullable: true description: Tags to associate with this line item items: type: string maxLength: 255 example: - priority - fragile custom_fields: type: object nullable: true description: Custom field values for this line item additionalProperties: oneOf: - type: string - type: number - type: boolean example: Lot Number: LOT-12345 volume_target_cbm: type: number format: float minimum: 0 nullable: true description: > Optionally set or update the purchase order's target container volume in cubic metres (the container-fill gauge's denominator) while appending line items. example: 67 examples: append_single_item: summary: Append a single line item value: items: - sku: WIDGET-001 quantity: 25 unit_price: 12.5 responses: '201': description: Line items appended; the updated purchase order is returned content: application/json: schema: type: object properties: data: type: object properties: id: type: integer description: Unique identifier for the purchase order order_numbers: type: array description: List of purchase order numbers items: type: string created_at: type: string format: date-time description: Timestamp when the purchase order was created updated_at: type: string format: date-time description: Timestamp when the purchase order was last updated order_status: type: string enum: - active - inactive - deleted description: Status of the purchase order order_date: type: string format: date description: Date when the purchase order was created invoice_date: type: string format: date description: Date when the purchase order was invoiced arrival_due_date: type: string format: date nullable: true description: Expected arrival date for the order requested_ship_date: type: string format: date nullable: true description: Requested shipping date order_type: type: integer description: Type of the order incoterm: type: string description: International Commercial Terms for the order tracking_info: type: string nullable: true description: Tracking information for the order payment_terms: type: string description: Payment terms for the order supplier_id: type: integer description: ID of the supplier item_count: type: integer description: Number of unique items in the order total_qty_ordered: type: number format: float description: Total quantity of line items ordered total_qty_received: type: number format: float description: Total quantity of line items received total_qty_remaining: type: number format: float description: >- Total quantity of line items remaining to be received (ordered - received) order_cost: type: number format: float description: Cost of the order before tax and shipping total_tax: type: number format: float description: Total tax amount total_shipping_cost: type: number format: float description: Total shipping cost total_cost: type: number format: float description: Total cost including tax and shipping total_paid: type: number format: float description: Total amount paid total_due: type: number format: float description: Total amount due total_volume_cbm: type: number format: float description: > Container-fill summary: total shipping volume in cubic metres, rolled up from each line item's box/carton dimensions × ordered quantity. `0` when no line item's SKU has usable dimensions. total_weight_kg: type: number format: float description: > Container-fill summary: total shipping weight in kilograms, rolled up from each line item's per-unit weight × ordered quantity. `0` when no line item's SKU has a weight set. lines_missing_dimensions: type: integer description: > Number of line items whose SKU lacks usable box/carton dimensions and therefore contribute nothing to `total_volume_cbm`. Useful for flagging an incomplete container-fill estimate. volume_target_cbm: type: number format: float nullable: true description: > Target container volume in cubic metres (the fill gauge's denominator), or `null` when no target has been set for this purchase order. volume_remaining_cbm: type: number format: float nullable: true description: > Remaining container volume in cubic metres, computed as `max(0, volume_target_cbm - total_volume_cbm)`. `null` when `volume_target_cbm` is not set. volume_fill_percent: type: number format: float nullable: true description: > How full the container is, as a percentage (`total_volume_cbm / volume_target_cbm × 100`). `null` when `volume_target_cbm` is not set or zero. down_payment: type: number format: float description: Down payment amount public_note: type: string nullable: true description: Public notes private_note: type: string nullable: true description: Private notes starred: type: boolean description: Whether the order is starred items: type: array description: >- Line items in the purchase order. Each is the same `PurchaseOrderItem` object served by `GET /purchase-orders/items`; on this detail endpoint the per-line `allocations` array is populated. items: type: object properties: id: type: integer description: Line item ID purchase_order_id: type: integer description: ID of the parent purchase order created_at: type: string format: date-time description: Creation timestamp updated_at: type: string format: date-time description: Last update timestamp quantity: type: number format: float description: >- How much was ordered, counted in the line's **ordered** unit of measure (the unit `ordered_unit_of_measure` names). A line ordered as 10 cases of 12 reads `10` here and `120` in `quantity_ordered`. unit_price: type: number format: float description: Price per unit unit: type: string nullable: true description: Unit of measure tax: type: number format: float description: Tax amount discount_amount: type: number format: float description: Discount amount line_total: type: number format: float description: Total for this line item expected_ship_date: type: string format: date nullable: true description: >- Per-line expected ship date override. When null, this line inherits the purchase order's header `requested_ship_date`. expected_arrival_date: type: string format: date nullable: true description: >- Per-line expected arrival date override. When null, this line inherits the purchase order's header `arrival_due_date`. quantity_received: type: number format: float description: >- How much has been received against this line, summed across receipts, in the **base** unit of measure. Each receipt line records the unit it was received in and stores its quantity already converted to base, so this total is reliably in one unit (DV-4147). It previously read a roll-up column that some receiving paths populated without converting, so this figure is no longer approximate on a line whose ordered and base units differ. received_quantity: type: number format: float deprecated: true description: >- **Deprecated (2026-08-13).** Identical value to `quantity_received`; use that field instead. Both keys are emitted from one computed value and can never diverge. No sunset date — the alias is retained indefinitely for backward compatibility. quantity_ordered: type: number format: float description: >- The same order as `quantity`, converted to the line's **base** unit of measure — not a second order. A line ordered as 10 cases of 12 reads `120` here and `10` in `quantity`. quantity_shipped: type: number format: float description: >- How much has shipped against this line, in the **ordered** unit of measure. Summed across every shipment line, each converted from the unit it was recorded in. Gross: no shipment-status filter. quantity_billed: type: number format: float description: >- How much has been billed against this line, in the **ordered** unit of measure. Summed across every linked bill line, each converted from its own unit. Gross and status-agnostic — drafts count, credits and returns are not netted off — and excluding lines whose bill was deleted. quantity_allocated: type: number format: float description: >- How much of this incoming line is already committed to a sales order, in the **base** unit of measure. The open purchase-to-order reservation; `0` on an unpegged line. quantity_released: type: number format: float description: >- Gross quantity released from pegs on this line — the received/fulfilled portion of the purchase-to-order reservation, in the **base** unit of measure. Additive to `quantity_allocated` (which stays open-only, so releasing a peg does not shrink it); `0` on an unpegged line. under_covered_quantity: type: number format: float description: >- How much of the open reservation on this line can no longer be covered by the effective remaining quantity — for example when the parent PO is **Completed** short, leaving effective remaining at `0`. Additive; `0` on an unpegged line or one whose open reservation is still fully coverable. remaining_to_ship: type: number format: float description: >- `quantity − quantity_shipped`, in the **ordered** unit of measure. **Signed** — over-shipping off a PO is a supported flow reconciled on the bill, so an over-shipped line reports the overage as a negative rather than `0`. remaining_to_receive: type: number format: float description: >- `quantity − quantity_received`. **Signed**, for the same reason as `remaining_to_ship`. The one figure here that spans two bases — `quantity` is the ordered unit and the received quantity is nominally the base unit (DV-4119) — so treat it as approximate on a line whose two units differ. available_to_allocate: type: number format: float description: >- How much of this incoming line is still free to commit to a sales order, in the **base** unit of measure: `max(0, quantity_ordered − quantity_received − quantity_allocated)`. **Floored at 0** (unlike the two signed figures above) because you cannot commit a negative quantity. Answers what is left to promise, not how far off the PO the delivery landed. Renamed from `quantity_remaining` (DV-4144). volume_cbm: type: number format: float description: > Per-unit shipping volume in cubic metres, derived from the SKU's box dimensions (falling back to carton dimensions). `0` when the SKU has no usable dimensions. Part of the container-fill summary. line_volume_cbm: type: number format: float description: > This line's total shipping volume in cubic metres (`volume_cbm` × `quantity_ordered`). weight_kg: type: number format: float description: > Per-unit shipping weight in kilograms. `0` when the SKU has no weight set. Part of the container-fill summary. line_weight_kg: type: number format: float description: > This line's total shipping weight in kilograms (`weight_kg` × `quantity_ordered`). allocations: type: array description: > Which sales orders currently hold the allocation on this line. Only populated on the single purchase-order detail endpoint (`GET /purchase-orders/{id}`); always an empty array on the list endpoint and for non-allocated lines. items: type: object properties: sales_order_id: type: integer description: >- ID of the sales order holding the allocation sales_order_number: type: string nullable: true description: Human-readable sales order number quantity_allocated: type: number format: float description: >- Open quantity this sales order has pegged to the line quantity_released: type: number format: float description: >- Quantity already released from this sales order's pegs on the line (the received/fulfilled portion). Rows are retained while either `quantity_allocated` or `quantity_released` is greater than `0`, so a fully-received allocation still appears with its release history. peg_ids: type: array items: type: integer description: > IDs of the pegs backing this allocation. Pass these to `POST /purchase-orders/reverse-allocation` (which is peg-scoped) to reverse an allocation made through the API. Allocate, read the peg ids back from `GET /purchase-orders/{id}`, then reverse them. source_sku: type: string nullable: true description: Source SKU from the supplier product: type: object nullable: true description: Associated product information properties: id: type: integer description: Product ID name: type: string description: Product name description: type: string nullable: true description: Product description retail_price: type: number format: float description: Product retail price wholesale_price: type: number format: float description: Product wholesale price unit_cost: type: number format: float description: Product unit cost product_weight: type: number format: float description: Product weight product_length: type: number format: float description: Product length (in inches) product_width: type: number format: float description: Product width (in inches) product_height: type: number format: float description: Product height (in inches) sellable: type: boolean description: Whether the product is sellable discontinued: type: boolean description: Whether the product is discontinued image_url: type: string nullable: true description: Product image URL variant_attributes: type: object nullable: true description: Product variant attributes sku: type: string description: Product internal SKU upc: type: string description: Product UPC/Barcode created_at: type: string format: date-time description: Product creation timestamp updated_at: type: string format: date-time description: Product last update timestamp base_unit_of_measure: type: object nullable: true description: Base unit of measure properties: id: type: integer name: type: string abbreviation: type: string ordered_unit_of_measure: type: object nullable: true description: Ordered unit of measure properties: id: type: integer name: type: string abbreviation: type: string lot: type: object nullable: true description: Product lot information properties: id: type: integer lot_number: type: string expiration_date: type: string format: date nullable: true supplier: type: object properties: id: type: integer status: type: integer name: type: string description: type: string street_address: type: string city: type: string state: type: string zip: type: string country: type: string contact_name: type: string contact_email: type: string contact_phone: type: string created_at: type: string format: date-time updated_at: type: string format: date-time custom_fields: type: object description: >- Read-only map of the supplier's custom field values as label => value pairs. Always a JSON object; empty when no custom fields are set. example: Region: Southwest Preferred Carrier: UPS payments: type: array description: Array of payments for this purchase order items: type: object properties: id: type: integer description: Unique identifier for the payment payment_date: type: string format: date description: Date of the payment payment_type: type: string enum: - cash - credit_card - debit_card - check - bank_transfer description: Type of payment paid_amount: type: number format: float description: Amount paid remarks: type: string nullable: true description: Payment remarks or notes external_id: type: string nullable: true description: External payment reference ID created_by: type: object description: User who created the payment properties: id: type: integer description: User ID name: type: string nullable: true description: User full name created_at: type: string format: date-time description: Timestamp when the payment was created updated_at: type: string format: date-time description: Timestamp when the payment was last updated ship_to: type: object nullable: true description: Shipping address information properties: address_1: type: string nullable: true description: Primary street address address_2: type: string nullable: true description: Secondary address line city: type: string nullable: true description: City name state: type: string nullable: true description: State or province zip: type: string nullable: true description: ZIP or postal code country: type: string nullable: true description: Country name default_ship_to_address: type: string enum: - ship_to_address - warehouse nullable: true description: Default shipping address preference warehouse_id: type: integer nullable: true description: >- ID of the destination warehouse. Always present (null when the PO has no warehouse set). location_id: type: integer nullable: true description: >- ID of the destination location within the warehouse. Always present (null when the PO has no location set). warehouse: type: object nullable: true description: >- Expanded warehouse object. Present when the warehouse relation is loaded (list and detail responses); omitted when the PO has no warehouse. properties: id: type: integer name: type: string location: type: object nullable: true description: >- Expanded location object. Present when the location relation is loaded (list and detail responses); omitted when the PO has no location. properties: id: type: integer name: type: string tags: type: array items: type: object properties: id: type: integer name: type: string description: type: string nullable: true icon: type: string nullable: true color: type: string nullable: true fulfillment_orders: type: array description: >- Linked fulfillment orders. Present when the relation is loaded; deduplicated by ID. items: type: object properties: id: type: integer order_number: type: string nullable: true order_status: type: string nullable: true '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string '404': description: Purchase order not found content: application/json: schema: type: object properties: message: type: string '409': description: >- Conflict - the purchase order is not active and cannot accept new line items content: application/json: schema: type: object properties: message: type: string '422': description: Unprocessable entity - validation error content: application/json: schema: type: object properties: message: type: string security: - BearerAuth: [] components: securitySchemes: BearerAuth: type: http scheme: bearer description: >- Authenticate using a bearer token. To create a token, navigate to /settings/api-tokens and click Create API Token. ````