> ## 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.

# Update a purchase order

> Update an existing purchase order. All fields are optional - only provided fields will be updated.

## Key Features
- Partial updates supported - only include fields you want to change
- Items can be added, updated, or removed
- If `items` array is provided, it replaces all existing items
- If `payments` array is provided, it replaces all existing payments
- Totals are automatically recalculated after updates
- Stock count updates - incoming quantities are automatically updated when items change

## Product Identification
For each line item, you must provide either:
- `product_id`: The internal product ID
- `sku`: The product SKU (supports both internal SKU and alternate SKUs)

## Updating Items
To update an existing item, include its `id` in the item object.
To add a new item, omit the `id` field.
To remove an item, omit it from the `items` array.

## Order Status Values
Valid order statuses include: `active`, `completed`, `deleted`

## Total Calculation
The order cost (`order_cost`) is automatically recalculated as:
`sum of (item quantities × unit prices)`

The order total (`total_cost`) is automatically recalculated as:
`order_cost + total_tax + total_shipping_cost`

Note: `order_cost`, `total_cost`, `total_paid`, and `total_due` are calculated automatically 
on the backend and cannot be edited directly.

## Payments
If `payments` array is provided, it replaces all existing payments for the order.
Totals are automatically recalculated after payments are updated.




## OpenAPI

````yaml /api-reference/build.yaml put /purchase-orders/{id}
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: Purchase Orders
    description: Get and modify purchase orders
  - 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/{id}:
    put:
      tags:
        - Purchase Orders
      summary: Update a purchase order
      description: >
        Update an existing purchase order. All fields are optional - only
        provided fields will be updated.


        ## Key Features

        - Partial updates supported - only include fields you want to change

        - Items can be added, updated, or removed

        - If `items` array is provided, it replaces all existing items

        - If `payments` array is provided, it replaces all existing payments

        - Totals are automatically recalculated after updates

        - Stock count updates - incoming quantities are automatically updated
        when items change


        ## Product Identification

        For each line item, you must provide either:

        - `product_id`: The internal product ID

        - `sku`: The product SKU (supports both internal SKU and alternate SKUs)


        ## Updating Items

        To update an existing item, include its `id` in the item object.

        To add a new item, omit the `id` field.

        To remove an item, omit it from the `items` array.


        ## Order Status Values

        Valid order statuses include: `active`, `completed`, `deleted`


        ## Total Calculation

        The order cost (`order_cost`) is automatically recalculated as:

        `sum of (item quantities × unit prices)`


        The order total (`total_cost`) is automatically recalculated as:

        `order_cost + total_tax + total_shipping_cost`


        Note: `order_cost`, `total_cost`, `total_paid`, and `total_due` are
        calculated automatically 

        on the backend and cannot be edited directly.


        ## Payments

        If `payments` array is provided, it replaces all existing payments for
        the order.

        Totals are automatically recalculated after payments are updated.
      operationId: updatePurchaseOrder
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: ID of the purchase order to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - order_date
                - supplier_id
                - items
              properties:
                order_date:
                  type: string
                  format: date
                  description: Date when the purchase order was created (YYYY-MM-DD)
                  example: '2024-01-15'
                supplier_id:
                  type: integer
                  description: ID of the supplier
                  example: 123
                warehouse_id:
                  type: integer
                  nullable: true
                  description: ID of the warehouse
                  example: 1
                location_id:
                  type: integer
                  nullable: true
                  description: ID of the location
                  example: 1
                order_status:
                  oneOf:
                    - type: string
                      enum:
                        - active
                        - production_started
                        - production_completed
                        - in_transit
                        - completed
                        - deleted
                    - type: integer
                      enum:
                        - 1
                        - 20
                        - 40
                        - 50
                        - 99
                        - -1
                  nullable: true
                  default: active
                  description: >
                    Milestone status (token or numeric id). Also accepts 30
                    (production_active) and 88 (delivered) by id.

                    Writes a milestone row and updates the PO header.
                  example: active
                order_numbers:
                  type: array
                  nullable: true
                  description: >-
                    Array of purchase order numbers used to identify the
                    purchase order across various systems
                  items:
                    type: string
                    maxLength: 255
                  example:
                    - PO-2024-001
                    - SUPPLIER-PO-123
                invoice_date:
                  type: string
                  format: date
                  nullable: true
                  description: Date when the purchase order was invoiced (YYYY-MM-DD)
                  example: '2024-01-16'
                total_shipping_cost:
                  type: number
                  format: float
                  minimum: 0
                  nullable: true
                  default: 0
                  description: Total shipping cost
                  example: 50
                total_tax:
                  type: number
                  format: float
                  minimum: 0
                  nullable: true
                  default: 0
                  description: Total tax amount
                  example: 80
                public_note:
                  type: string
                  nullable: true
                  description: Public notes visible to suppliers
                  example: Please ship via express delivery
                private_note:
                  type: string
                  nullable: true
                  description: Internal private notes
                  example: Rush order - expedite processing
                requested_ship_date:
                  type: string
                  format: date
                  nullable: true
                  description: Requested shipping date (YYYY-MM-DD)
                  example: '2024-01-20'
                arrival_due_date:
                  type: string
                  format: date
                  nullable: true
                  description: Expected arrival date (YYYY-MM-DD)
                  example: '2024-01-25'
                ship_to:
                  type: object
                  nullable: true
                  description: Shipping address information
                  properties:
                    address_1:
                      type: string
                      maxLength: 255
                      nullable: true
                      description: Primary street address
                      example: 123 Main Street
                    address_2:
                      type: string
                      maxLength: 255
                      nullable: true
                      description: Secondary address line (apt, suite, etc.)
                      example: Suite 100
                    city:
                      type: string
                      maxLength: 255
                      nullable: true
                      description: City name
                      example: Anytown
                    state:
                      type: string
                      maxLength: 255
                      nullable: true
                      description: State or province
                      example: CA
                    zip:
                      type: string
                      maxLength: 255
                      nullable: true
                      description: ZIP or postal code
                      example: '90210'
                    country:
                      type: string
                      maxLength: 255
                      nullable: true
                      description: Country name
                      example: United States
                    default_ship_to_address:
                      type: string
                      enum:
                        - ship_to_address
                        - warehouse
                      nullable: true
                      description: Default shipping address preference
                      example: warehouse
                items:
                  type: array
                  minItems: 1
                  description: Array of line items for the purchase order
                  items:
                    type: object
                    required:
                      - quantity
                      - unit_price
                    properties:
                      id:
                        type: integer
                        nullable: true
                        description: Line item ID (only used for updates)
                        example: 456
                      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
                        default: 0
                        description: Quantity already received
                        example: 5
                      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 received 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
                        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
                          Expiry Date: '2024-12-31'
                payments:
                  type: array
                  nullable: true
                  description: >
                    Array of payments for this purchase order. If provided,
                    replaces all existing payments.

                    Totals are automatically recalculated after payments are
                    updated.
                  items:
                    type: object
                    required:
                      - payment_date
                      - payment_type
                      - paid_amount
                    properties:
                      payment_date:
                        type: string
                        format: date
                        description: Date of the payment (YYYY-MM-DD)
                        example: '2024-01-15'
                      payment_type:
                        type: string
                        enum:
                          - cash
                          - credit_card
                          - debit_card
                          - check
                          - bank_transfer
                        description: Type of payment
                        example: check
                      paid_amount:
                        type: number
                        format: float
                        minimum: 0.01
                        description: Amount paid
                        example: 500
                      remarks:
                        type: string
                        maxLength: 1000
                        nullable: true
                        description: Payment remarks or notes
                        example: 'Check #1234'
                      external_id:
                        type: string
                        maxLength: 255
                        nullable: true
                        description: External payment reference ID
                        example: PAY-EXT-12345
                custom_fields:
                  type: object
                  nullable: true
                  description: Custom field values for the purchase order
                  additionalProperties:
                    oneOf:
                      - type: string
                      - type: number
                      - type: boolean
                  example:
                    Customer PO: PO-98765
                    Priority Level: High
                tags:
                  type: array
                  nullable: true
                  description: Tags to associate with the purchase order
                  items:
                    type: string
                    maxLength: 255
                  example:
                    - urgent
                    - priority
                    - rush-order
            examples:
              update_status:
                summary: Update order status only
                description: Update just the order status
                value:
                  order_status: completed
              update_items:
                summary: Update items
                description: Replace all items in the order
                value:
                  items:
                    - id: 789
                      quantity: 20
                      unit_price: 49.99
                    - product_id: 456
                      quantity: 5
                      unit_price: 29.99
              update_payments:
                summary: Update payments
                description: Replace all payments for the order
                value:
                  payments:
                    - payment_date: '2024-01-15'
                      payment_type: check
                      paid_amount: 1000
                      remarks: 'Check #5678'
      responses:
        '200':
          description: Purchase order updated successfully
          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
                      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
                        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: integer
                              description: Quantity ordered
                            unit_price:
                              type: number
                              format: float
                              description: Price per unit
                            unit:
                              type: string
                              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
                            received_quantity:
                              type: integer
                              description: Quantity received
                            source_sku:
                              type: string
                              nullable: true
                              description: Source SKU
                            product:
                              type: object
                              properties:
                                id:
                                  type: integer
                                name:
                                  type: string
                                description:
                                  type: string
                                  nullable: true
                                retail_price:
                                  type: number
                                  format: float
                                wholesale_price:
                                  type: number
                                  format: float
                                variant_attributes:
                                  type: object
                                  nullable: true
                                sku:
                                  type: string
                                upc:
                                  type: string
                                created_at:
                                  type: string
                                  format: date-time
                                updated_at:
                                  type: string
                                  format: date-time
                      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
                      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:
                        type: object
                        nullable: true
                        description: Warehouse information
                        properties:
                          id:
                            type: integer
                          name:
                            type: string
                      location:
                        type: object
                        nullable: true
                        description: Location information
                        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
        '400':
          description: Bad request - validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '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
      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.

````