[Extensibility Request] issue 30434: add purchase prepayment amount event

[Marko Aleksandric (AleksandricMarko)]

Summary

Extensions cannot currently override the prepayment amount calculated for purchase documents, even though the equivalent sales calculation is extensible. This change adds a handled event before the purchase prepayment calculation so subscribers can provide the result when standard logic does not meet their requirements.

Source issue repository: microsoft/AlAppExtensions; issue number: 30434

Changes Made

• Purchase-Post Prepayments.PrepmtAmount - added OnBeforePrepmtAmount with an overridable result and propagated the event to all existing layer counterparts while preserving localized calculation logic

Fixes AB#647921

[github-actions]

$\textbf{🟡\ Medium\ Severity\ —\ events}$

In the NA layer, the overloaded PrepmtAmount(PurchLine, DocumentType, IncludeTax) computes a different result depending on the IncludeTax Boolean, but the new OnBeforePrepmtAmount event does not expose or forward that parameter. A subscriber handling this event has no way to know whether it must return a tax-inclusive or tax-exclusive amount, so any override risks producing an incorrect Result for one of the two cases. The other 5 layers (APAC, ES, IT, NL, W1) only have the 2-parameter overload and are unaffected — the gap is specific to NA. Recommend adding IncludeTax: Boolean to the OnBeforePrepmtAmount signature in the NA layer and passing it from the publisher call.

_{Agent judgement — not directly backed by a BCQuality knowledge article.}

Line mapping was unavailable, so this was posted as an issue comment.

_{👍 useful · ❤️ especially valuable · 👎 wrong - reply with why · AL review agent v1.35.4}

[alexei-dobriansky]

Good Sense Reviewer - Round 1

Recommendation: Accept with Suggestions

What this PR does

The change adds OnBeforePrepmtAmount to the purchase prepayment amount calculation in each BaseApp layer. It changes PrepmtAmount to use a named Result, raises the publisher before the standard case statement, and exits only when IsHandled is set.

This keeps current behavior unchanged when there is no subscriber. The placement matches the sales-side pattern and passes the purchase line by var, the document type, the result, and the handled flag, so subscribers can replace the returned amount when needed.

Problem-solution fit

Fit: Strong

The requested behavior is an override point before the purchase prepayment amount is calculated. The diff adds that handled publisher at the start of the calculation in every current purchase layer and preserves the standard calculation when the event is not handled.

Suggestions

S1 (🟠 Moderate): Expose IncludeTax in NA event
The NA overload can return tax-inclusive or tax-exclusive amounts. Pass IncludeTax to OnBeforePrepmtAmount in the NA layer so subscribers know which final amount to return. This avoids extensions needing to re-read the header and keeps the event contract clear.

Risk assessment and necessity

Risk: The regression surface is codeunit 444 purchase prepayment amount calculation in W1, APAC, ES, IT, NA, and NL. Standard behavior is unchanged unless a subscriber sets IsHandled, so the main risk is the public event contract; the NA layer has extra tax-inclusion context that affects the final amount.

Necessity: The change is needed because purchase prepayment amount calculation has no matching override point while the parallel sales calculation already has one. The scope is narrow and limited to the publisher plus the early handled exit in the existing calculation procedures.

---

[AI-PR-REVIEW] version=1 promptVersion=4 system=github pr=10898 round=1 by=alexei-dobriansky at=2026-09-02T00:13:14.9719945Z lastSha=7f0476e680e212a629e9ec1a78232850ee670249 reviewKey=8697b0e8c9e609bebb07facf17f07ae40de466a39e22abc16ddffcfe3e0811d2 suggestions=S1@91565f4a

[alexei-dobriansky]

Please check the suggestion.

[github-actions]

⚠️ Stale Status Check Deleted

The Pull Request Build workflow run for this PR was older than 72 hours and has been deleted.

📋 Why was it deleted?

Status checks that are too old may no longer reflect the current state of the target branch. To ensure this PR is validated against the latest code and passes up-to-date checks, a fresh build is required.

---

🔄 How to trigger a new status check:

1. 📤 Push a new commit to the PR branch, or
2. 🔁 Close and reopen the PR

This will automatically trigger a new Pull Request Build workflow run.