{"title":"Extending Item Charge Distribution Methods","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-extending-item-charges/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-extending-item-charges, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-extending-item-charges","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"How you extend item charges in Dynamics 365 Business Central.","date":"2021-04-01","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Extending Item Charge Distribution Methods","slug":"extending-item-charge-distribution-methods","at":0,"chars":11329},{"level":2,"title":"To add a new option to the item charges distribution methods","slug":"to-add-a-new-option-to-the-item-charges-distribution-methods","at":2551,"chars":1215},{"level":2,"title":"To add a new distribution method for item charges","slug":"to-add-a-new-distribution-method-for-item-charges","at":3766,"chars":6188},{"level":2,"title":"To call the new distribution method","slug":"to-call-the-new-distribution-method","at":9954,"chars":1042},{"level":2,"title":"Related information","slug":"related-information","at":10996,"chars":333}],"text":"# Extending Item Charge Distribution Methods\nTo ensure correct valuation, your inventory items must carry any added costs, such as freight, physical handling, insurance, and transportation that you incur when purchasing or selling the items.\nUsers can add these costs by adding a Charge (Item) line to the involved purchase or sales document. See Use Item Charges to Account for Additional Trade Costs<https://learn.microsoft.com/dynamics-nav-app/payables-how-assign-item-charges> in application help.\nItem charges are distributed over other item lines in the document according to a distribution method. Dynamics 365 Business Central offers four distribution methods out of the box: Equally, By Amount, By Weight, and By Volume. This article explains how to remove or add item charge distribution methods. The article describes the method for purchases. The steps are similar for sales, except the events are located in codeunit 5807, Item Charge Assgnt. (Sales).\nTo enable extension of item charges distribution methods, two events can be found in codeunit 5805, Item Charge Assgnt. (Purch.). The work consists of the following two tasks:\n1. In the OnBeforeShowSuggestItemChargeAssignStrMenu event, you manipulate the options that are presented to users. You can remove, add, and change the order of the options.\n  Keep in mind that other extensions may also manipulate the options.\n  You should not assume that an option will exist, nor should you write code that may remove an option added by another extension.\n2. In the OnAssignItemCharges event, you distribute the item charge amount over the item lines according to your new distribution method.\n  You must verify that the option selected by the user is your new option. If it is not, then exit without taking action.\n  When you have distributed the amount over the lines, you must set the ItemChargesAssigned boolean to true. If you do not set this boolean to true, an error will occur.\nThe following procedures show how to extend the item charges distribution methods:\n1. Add a new option to the item charges distribution methods in the OnBeforeShowSuggestItemChargeAssignStrMenu event.\n2. Add a new distribution method for item charges.\n3. Call the new distribution method in the OnAssignItemCharges event.\nThe procedures are based on an example where the By Fairy Dust option is added to the string menu (STRMENU) and added to the CASE statement.\n> NOTE\n> To complete this example you will have to add a new field Fairy Dust to the Purchase Line table and other relevant tables and pages.\n## To add a new option to the item charges distribution methods\nCreate a new codeunit and add an event subscriber to the OnBeforeShowSuggestItemChargeAssignStrMenu event.\n```al\ncodeunit 50100 \"Item Ch. Assign by Fairy Dust\"\n{\n    var\n        ByFairyDustTok: Label 'By Fairy Dust';\n\n    local procedure AssignByFairyDustMenuText(): Text\n    begin\n        exit(ByFairyDustTok)\n    end;\n\n    [EventSubscriber(ObjectType::Codeunit, Codeunit::\"Item Charge Assgnt. (Purch.)\", 'OnBeforeShowSuggestItemChargeAssignStrMenu', '', false, false)]\n    local procedure AddByFairyDustOnBeforeShowSuggestItemChargeAssignStrMenu(PurchLine: Record \"Purchase Line\"; var SuggestItemChargeMenuTxt: Text; var SuggestItemChargeMessageTxt: Text; var Selection: Integer)\n    begin\n        // if 'By Fairy Dust' is not in the menu options, add it at the end\n        if StrPos(SuggestItemChargeMenuTxt, AssignByFairyDustMenuText) = 0 then begin\n            SuggestItemChargeMenuTxt += ',' + AssignByFairyDustMenuText;\n            // make the last option ('By Fairy Dust') the default selection\n            Selection := StrLen(DelChr(SuggestItemChargeMenuTxt, '=', DelChr(SuggestItemChargeMenuTxt, '=', ','))) + 1;\n        end;\n    end;\n}\n```\n## To add a new distribution method for item charges\nIn the new codeunit, add functions to distribute the charges over the item lines.\n> NOTE\n> The GetItemValues procedure in the example below uses a with statement, which is deprecated since Business Central 2020 release wave 2. In new code, qualify field access with the record variable name instead. See Deprecating explicit and implicit with statements<devenv-deprecating-with-statements-overview>.\n```al\n    local procedure AssignByFairyDust(var ItemChargeAssignmentPurch: Record \"Item Charge Assignment (Purch)\"; Currency: Record Currency; TotalQtyToAssign: Decimal; TotalAmtToAssign: Decimal)\n    var\n        TempItemChargeAssgntPurch: Record \"Item Charge Assignment (Purch)\" temporary;\n        LineArray: array[2] OF Decimal;\n        TotalFairyDust: Decimal;\n        QtyRemaining: Decimal;\n        AmountRemaining: Decimal;\n    begin\n        // copy lines to temp variable and calculate total Fairy Dust\n        repeat\n            if not ItemChargeAssignmentPurch.PurchLineInvoiced then begin\n                TempItemChargeAssgntPurch.Init();\n                TempItemChargeAssgntPurch := ItemChargeAssignmentPurch;\n                TempItemChargeAssgntPurch.Insert(false);\n                GetItemValues(TempItemChargeAssgntPurch, LineArray);\n                TotalFairyDust += (LineArray[2] * LineArray[1]);\n            end;\n        until ItemChargeAssignmentPurch.Next = 0;\n\n        if TempItemChargeAssgntPurch.Findset(true) then\n            repeat\n                // Calculate Fairy Dust to assign to the line\n                GetItemValues(TempItemChargeAssgntPurch, LineArray);\n                if TotalFairyDust <> 0 then\n                    TempItemChargeAssgntPurch.\"Qty. to Assign\" :=\n                      (TotalQtyToAssign * LineArray[2] * LineArray[1]) / TotalFairyDust + QtyRemaining\n                else\n                    TempItemChargeAssgntPurch.\"Qty. to Assign\" := 0;\n\n                // Assign Fairy Dust to the line and calculate the remaining Fairy Dust to assign\n                ItemChargeAssignmentPurch.Get(\n                  TempItemChargeAssgntPurch.\"Document Type\",\n                  TempItemChargeAssgntPurch.\"Document No.\",\n                  TempItemChargeAssgntPurch.\"Document Line No.\",\n                  TempItemChargeAssgntPurch.\"Line No.\");\n                ItemChargeAssignmentPurch.\"Qty. to Assign\" := Round(TempItemChargeAssgntPurch.\"Qty. to Assign\", 0.00001);\n                ItemChargeAssignmentPurch.\"Amount to Assign\" :=\n                  ItemChargeAssignmentPurch.\"Qty. to Assign\" * ItemChargeAssignmentPurch.\"Unit Cost\" + AmountRemaining;\n                AmountRemaining := ItemChargeAssignmentPurch.\"Amount to Assign\" -\n                  Round(ItemChargeAssignmentPurch.\"Amount to Assign\", Currency.\"Amount Rounding Precision\");\n                QtyRemaining := TempItemChargeAssgntPurch.\"Qty. to Assign\" - ItemChargeAssignmentPurch.\"Qty. to Assign\";\n                ItemChargeAssignmentPurch.\"Amount to Assign\" :=\n                  Round(ItemChargeAssignmentPurch.\"Amount to Assign\", Currency.\"Amount Rounding Precision\");\n                ItemChargeAssignmentPurch.Modify(false);\n\n            until TempItemChargeAssgntPurch.Next = 0;\n        TempItemChargeAssgntPurch.DeleteAll(false);\n    end;\n\n    procedure GetItemValues(TempItemChargeAssgntPurch: Record \"Item Charge Assignment (Purch)\" temporary; var DecimalArray: Array[2] of Decimal)\n    var\n        PurchaseLine: Record \"Purchase Line\";\n        PurchRcptLine: Record \"Purch. Rcpt. Line\";\n        ReturnShptLine: Record \"Return Shipment Line\";\n        TransferRcptLine: Record \"Transfer Receipt Line\";\n        SalesShptLine: Record \"Sales Shipment Line\";\n        ReturnRcptLine: Record \"Return Receipt Line\";\n    begin\n        // Get the Fairy Dust for the line\n        Clear(DecimalArray);\n        with TempItemChargeAssgntPurch do\n            case \"Applies-to Doc. Type\" of\n                \"Applies-to Doc. Type\"::Order,\n                \"Applies-to Doc. Type\"::Invoice,\n                \"Applies-to Doc. Type\"::\"Return Order\",\n                \"Applies-to Doc. Type\"::\"Credit Memo\":\n                    begin\n                        PurchaseLine.Get(\"Applies-to Doc. Type\", \"Applies-to Doc. No.\", \"Applies-to Doc. Line No.\");\n                        DecimalArray[1] := PurchaseLine.Quantity;\n                        DecimalArray[2] := PurchaseLine.\"Fairy Dust\";\n                    end;\n                \"Applies-to Doc. Type\"::Receipt:\n                    begin\n                        PurchRcptLine.Get(\"Applies-to Doc. No.\", \"Applies-to Doc. Line No.\");\n                        DecimalArray[1] := PurchRcptLine.Quantity;\n                        DecimalArray[2] := PurchRcptLine.\"Fairy Dust\";\n                    end;\n\n                \"Applies-to Doc. Type\"::\"Return Receipt\":\n                    begin\n                        ReturnRcptLine.Get(\"Applies-to Doc. No.\", \"Applies-to Doc. Line No.\");\n                        DecimalArray[1] := ReturnRcptLine.Quantity;\n                        DecimalArray[2] := ReturnRcptLine.\"Fairy Dust\";\n                    end;\n                \"Applies-to Doc. Type\"::\"Return Shipment\":\n                    begin\n                        ReturnShptLine.Get(\"Applies-to Doc. No.\", \"Applies-to Doc. Line No.\");\n                        DecimalArray[1] := ReturnShptLine.Quantity;\n                        DecimalArray[2] := ReturnShptLine.\"Fairy Dust\";\n                    end;\n                \"Applies-to Doc. Type\"::\"Transfer Receipt\":\n                    begin\n                        TransferRcptLine.Get(\"Applies-to Doc. No.\", \"Applies-to Doc. Line No.\");\n                        DecimalArray[1] := TransferRcptLine.Quantity;\n                        DecimalArray[2] := TransferRcptLine.\"Fairy Dust\";\n                    end;\n                \"Applies-to Doc. Type\"::\"Sales Shipment\":\n                    begin\n                        SalesShptLine.Get(\"Applies-to Doc. No.\", \"Applies-to Doc. Line No.\");\n                        DecimalArray[1] := SalesShptLine.Quantity;\n                        DecimalArray[2] := SalesShptLine.\"Fairy Dust\";\n                    end;\n            end;\n    end;\n```\n## To call the new distribution method\nIn the new codeunit, add a subscriber to the OnAssignItemCharges event.\n```al\n    [EventSubscriber(ObjectType::Codeunit, Codeunit::\"Item Charge Assgnt. (Purch.)\", 'OnAssignItemCharges', '', false, false)]\n    local procedure AssignByFairyDustOnAssignItemCharges(SelectionTxt: Text; var ItemChargeAssignmentPurch: Record \"Item Charge Assignment (Purch)\"; Currency: Record Currency; PurchaseHeader: Record \"Purchase Header\"; TotalQtyToAssign: Decimal; TotalAmtToAssign: Decimal; var ItemChargesAssigned: Boolean)\n    begin\n        // if item charges are already assigned, exit\n        if ItemChargesAssigned then\n            exit;\n        // if the user did not choose 'By Fairy Dust', exit\n        if not (SelectionTxt = AssignByFairyDustMenuText) then\n            exit;\n        // assign item charges by fairy dust\n        AssignByFairyDust(ItemChargeAssignmentPurch, Currency, TotalQtyToAssign, TotalAmtToAssign);\n        // charges have been assigned\n        ItemChargesAssigned := true;\n    end;\n```\n## Related information\ndevenv-extending-application-areas\nModule System Application<https://learn.microsoft.com/dynamics365/business-central/application/system-application/module/system-application>\nModule Base Application<https://learn.microsoft.com/dynamics365/business-central/application/base-application/module/base-application>"}