Sales Order Kitting



The goal of the feature is to enable users to sell kit items on a sales order that automatically explode to shippable line item components. The kit components are printed on the sales order pick list, issued to stock and shipped. This needs to be accomplished without an intermediary work order. This functionality will be made available in all editions of xTupleERP.

Functional Requirements

This feature must include the following elements:

  • A new item type called "Kit"
  • Kit items added to a sales order automatically "explode" to their constituent line items
  • A Sub line number is added to the sales order; kit children are sub line items of the parent
  • Kit sub components are displayed as an indented tree on the sales order
  • Kit sub components are view-only on the sales order
  • Kit sub components appear on the sales order pick list
  • Kit sub components may be issued to shipping, the parent item may not
  • The automatic "Select for Billing" option takes effect for kit items when all kit items are shipped

New Terms and Definitions


    • An Item type that automatically explodes Bill of Material items on to a sales order for shipping.

Related Existing Functionality

The Job item type allows for kit-like behavior when all bill of material items for the parent are set to back flush. However, an intermediate work order is required for a job item. Also individual items may be issued, but not shipped, which makes tracking partial shipments of Job items problematic.

The work order system in xTuple uses the notion of a "Sub Number" to differentiate between work orders with a parent/child relationship. The same nomenclature will be used on sales orders to identify kit child items with parent line numbers.

Similar and Related Requests

Issue 6883 is the driving issue for this specification.

Issue 4818 requests the ability to sell phantom items to approximate kitting behavior.

There is a forum topic asking how to kit items here.

User-Level Functionality

Users will define an item as a "Kit" in the Item maintenance window. Users will be allowed to create Bills of Materials for kit items. When a kit item is saved on a sales order, sub line items will be exploded out underneath the kit. Users will be able to view the sub components on the sales order by expanding an indented list of sub items under the parent kit item. The sub items will be view only.

The kit items will appear on sales order pick lists as with any other items. Kit sub components will be issued to stock as with any other items, however the parent kit item will not be visible or issuable in the issue to stock window.

Window Changes


The new "kit" item type will be added and available to Item maintenance. The following rules concerning kit items will apply:

  • Fractional check box will be unchecked and disabled
  • Planning system will be set to "None" and disabled
  • Configure check box will be disabled
  • Kit items must be sold. Sold check box will be checked and disabled
  • The Bill of Operations button will be disabled
  • The Item Availability workbench will be disabled
  • The UOM conversion tab will be disabled
  • The transformations tab will be disabled

Item Site

Kits will not be inventory items, so generally no inventory rules will apply to them. From a practical standpoint the Item Site window will basically just define whether the kit is available for sale from the item site or not. The following rules will apply to the item site window for kits:

  • The "Supplied at this site" check box will be unchecked and disabled
  • Costing methods will be disabled and "None" will be selected
  • Control method will be disabled and "None" will be selected
  • Cost category will be blank and disabled
  • The inventory, planning and restricted locations tabs will be disabled

Bill of Materials

Bill of Materials Items for kits will behave like any other for the most part with the following exceptions:

  • The issue method will be set to "Push" and disabled
  • The "Create Child Work Orders" option will be disabled
  • The "Used at" option will be disabled
  • Substitutions will be disabled
  • Kits themselves may not be added as a bill of material item to any bill of materials

Bill of Operations

Kits will not support or allow a Bill of Operations.


Costing and cost roll ups for kit items will behave the same as a manufactured item, except that it will be entirely informational since no inventory transactions will be possible for kit items.

Sales Order

A kit item on a sales order line item will behave like any other item, except that when it is saved, sub line items for all bill of material items on the kit will exploded as sub line items on the sales order. This will appear as an indented tree on the Sales order window where the sub numbers are listed sequentially under the line number:








My Kit Example





My Kit sub item A





My Kit sub item B





Blue Truck



The line number will be concatenated with a period and the sub line number to uniquely identify the row. Sub line items will be viewable but not editable. They will always have a price of zero. Sub line items may be issued to stock from the Sales Order Window, while the parent kit item itself may not.

If the parent item is deleted, all kit child items should be deleted.

Issue stock to Shipping

Kit sub items will appear on the Issue Stock to Shipping window with the same dot nomenclature for line numbering described for sales orders. However, the list on Issue Stock to Shipping will not be indented and the parent kit item will not appear on the list. Otherwise the Issue Stock to Shipping screen will appear and operate as it does currently.

Ship and Select for Billing

The Ship window will be have as is does today, with the one additional special qualifier that when "Select for Billing" is checked, a parent kit item will be selected for billing when all the child items have shipped complete. However, as with any other item type, kit items may be manually selected for billing at any time.

The Select for Billing behavior of kit child items will be the same as any other item. However, since they never have a price, they will always invoice for zero dollars.

Report Changes

The Pick List and Packlist reports should be made to show the dot nomenclature for line numbering described above. As with the issue stock to shipping screen, the kit itself should not appear on the pick list since it is not itself an inventory item to be picked.

Problems and Alternatives

There is some question as to whether and when kit parent items should appear on pick lists and invoice paper work. Do users want to be able to see the kit parent on the picklist simply for informational purposes? If so it seems like this could introduce confusion to pickers that would have to "know" it is a kit, or yet more information would have to be added to indentify it as a kit. It seems like the cleanest solution is to simply limit the pick list to shippable items. If an argument is made that kit items need to be containerized together as single unit, that would seem to make the case for using job items instead.

Another potential issue is that while kit components will appear on invoices for partial shipments, the parent will not appear until it is invoiced itself. Will this cause confusion showing sub components without the parent kit? It may, but the alternative of adding the parent kit to the invoice when it is not actually being invoiced seems even more confusing. Again, it seems that the cleanest approach is to simply include on the invoice what was shipped and billed.

As an alternative to the algorithm to only select kits for billing when all items have been shipped, the sponsor of this feature may want to invoice when any kit sub item has shipped. We can easily change the specification to work that way if that is the desired behavior. If the desired behavior is to bill proportionally to what was shipped, any effort to handle that in a automated way is likely to turn out to be unreliable. In that case it would probably be best to manually select for billing appropriate portions as deemed necessary.

There are some fairly rigid rules below describing restrictions to changes that may be made to a kit parent once shipping activity has been recorded against any of the child items. Alternatively we could allow users to edit kit sub item quantities if the sponsor requires more flexibility. Which ever is the final decision by the sponsor, it is likely some user in the future will want the opposite behavior. In that case we could implement a global option or privilege to allow or disallow kit child editing as a configuration option. For now such an option goes beyond the necessary scope of this specification; we need to confirm the requirements of the sponsor.

Internal Design

Basic Algorithms

A kit explosion function explodekit should be created to explode the kit into its constituent components and add them to the sales order. It will need to be able to loop through phantom items where applicable. This function should initially be called when a sales line is inserted.

PASS IN cohead_id,coitem_linenumber,coitem_subnumber,itemsite_id

DECLARE Sub Number, Bomitem

For each bomitem on the current revision of the itemsite item passed
  If the item is a phantom
    Sub Number=Run explode kit function based on item site for current bom item
  Else If the item is not active in the current warehouse
    Throw an error that the item site is invalid
    Sub Number = Sub Number + 1
    Insert sales order item for the child based on current info
Next Loop

RETURN Sub Number

These additional rules and behaviors apply when sales order lines for kit items are changed:

  • When a sales line for a kit is deleted, the sales line trigger should delete all kit child items, provided none have been issued to shipping.
  • If a kit item for a sales line is closed or canceled, the trigger should likewise close or cancel all open sub line items.
  • If the parent is reopened, all sub line items that were shipped incomplete should be reopened.
  • If the quantity of the parent is changed the kit line items should be deleted and the kit re-exploded, provided no kit items have already been issued.

A line item number formatting function called formatsolinenumber should be created to for display and reporting purposes:

PASS IN coitem

DELCLARE line number
  If coitem line sub number > 0
    line number = Concatenate sales order line number, dot, and sub number
    line number = sales order line number

RETURN line number

The selectbalanceforbilling function will need the following additions

Execute existing algorithm
Change in loop....

If item is not type kit
  select for billing
  If all kit child items have been shipped
    select for billing

... continue existing

Schema Changes

Addition to the coitem table

Column Name


Data Type



Kit sub number


Defaults to zero.

The current unique constraint on coitem_cohead_id and coitem_linenumber will need to be replaced with one that also includes coitem_subnumber.

Changes to the API views

The salesline API view will need to be changed to present the dot line number nomenclature. In particular, the insert and update rules will have to be modified to decode the line number. If basic algorithms above are implemented at the trigger level, all other business logic should already be included at the database level.

Performance Considerations

None expected

Error Handling

Once any kit sub item has been shipped, the quantity of the parent item should not be allowed to be changed. Clear error messages should be made to explain this restriction where applicable.

QA Considerations

The sales order cycle with and without kits should be tested extensively. Make sure to include phantoms in kit testing and to test the API views as well.

Documentation Considerations

Standard documentation rules apply. A wiki topic or video presentation may be appropriate for this feature.

Release Considerations

We have committed this functionality to be released to the sponsor in version 3.1 of xTuple ERP.