Professional Documents
Culture Documents
Overview and Setup for Project Retention Billing Functionality (Doc ID 2752607.1)
In this Document
Purpose
Scope
Details
Overview
Setups Required For Retention Billing
Define Retention Level
Define Retention Term
Withholding Terms:
Withholding Terms by Expenditure Category:
Withholding Terms by Event Revenue Category:
Billing Term:
Accounting for Unbilled Retention
Retention Format
Retention Billing Format
Process Flow For Retention Billing
Case 1: Validate Withholding Term
Enter Event
Generate Draft Invoice
Interface Invoice
Create another Event
Generate Invoice
Generate Invoice
Case 2: Validate Withholding Term with Expenditure Category
Enter Expenditure Item with type
Generate Invoice
Case 3: Validate Withholding Term with Revenue Category
Enter Event with event type Customer Deposit
Generate Invoice
Case 4: Validate Withholding Term Effective Date
Enter Event with event date 01-NOV-2019
Generate Invoice
Review Retention Amounts
Technical Components
Basic Data Model
Client Extension
Important Issues and FAQ
Issues
Frequently Asked Questions
APPLIES TO:
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 1/24
10/16/23, 6:09 PM Document Display
PURPOSE
This document addresses functionality and setup required for project retention billing along with some known issue and
frequently asked questions on project retention billing.
SCOPE
Focus of this setup is Oracle Project Billing Release 12. Although most of the content in this note is also applicable in
Release 11.5
DETAILS
Overview
This section gives overview of retention billing which is one of the methodology to bill clients based on special contractual
provisions.
In traditional invoicing model, Bills are generated either based on specific milestone events or based on the work
performed on project and Client has to pay the invoice amount in full however in many business scenario Client has a
contract with business to withhold some portion of billing amount and after a later point of time Client will pay withheld
amount, and in such scenarios retention billing model is utilized.
Consider an example where ERP is being implemented for a customer by a consultancy organization. Before execution of
the project, Consultancy Organization and Client had a contract where for any billing of labour efforts 20% of the amount
will be withheld by Client and that 20% will be billed after User Acceptance Testing is completed. Assume total
development effort for the implementation is $10K thus as per contract only $8K will be delivered to Client and remaining
retention amount $2K will be delivered at a later stage of the project.
Retention can be defined either at Project level or at task level. Thus if client wishes to withheld some amount only for
specific tasks then it can be met as well. Also if there is a requirement to withhold amount only for specific kind of
expenditure or even then also retention term can be defined based on expenditure category or revenue category. All these
facets of retention billing will be discussed in coming sections.
If a project has more than one customers then retention can be defined multiple times as retention terms are defined
based on customer for a project.
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 2/24
10/16/23, 6:09 PM Document Display
Client can have a contract with business to withhold amount for specific task instead of whole project. For example Client
may withhold amount for Development task of project but as per contract they have to pay full amount for Design Task.
Thus to meet this kind of requirement project manager has to define retention at task level.
Retention can be defined either at Project Level or at Top Task Level, It cannot be defined for lowest task or any mid-level
task.
If there are multiple customers associated to same project then retention level can be different for each customer.
Retention term determines how invoice amounts can be withheld and also determines how withheld amount can be billed
on later stage of project. There are three type of withholding terms which can be defined for a project or top task
depending on retention level.
1. Withholding Terms
2. Withholding Terms by Expenditure Category
3. Withholding Terms by Event Revenue Category
Retention term can also be used to determine how withholding amount can be billed. This can be determined through
“Billing Term”.
Withholding Terms:
If requirement is to withhold amount for all the invoices for specific project or task then implementer has to setup
Withholding term.
Withholding term can be defined based on Amount or Percentage. To add withholding term please follow below steps.
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 3/24
10/16/23, 6:09 PM Document Display
Withholding Percentage: This determines what percentage of amount is going to be withheld for each invoice within
withholding term.
For example: When invoice is generated for 1000 USD and withholding percentage is 20% then 200 USD will be withheld
and 800 USD will be delivered to customer. This continues for each invoices until term ends.
Withholding Amount: This determines what exact amount is going to be withheld for each invoice within withholding
term.
For example: When invoice is generated for 1000 USD and withholding amount is 150 USD then 150 USD will be withheld
and 850 USD will be delivered to customer. This continues for each invoices until term ends.
User cannot enter values in both Withholding Amount and Withholding Percentage while defining term.
Threshold Amount: This is an optional field and determines how much maximum amount can be withheld.
For Example: If Threshold amount is set as 3000 USD and withholding percentage as 20%. If there are four invoices
created with 5000 USD then total withholding amount for first three invoices will be 3000 USD and fourth invoice will be
delivered as it is to customer as threshold amount is reached by first three invoices.
Thus delivered amount for first three invoices will be 4000 USD and for fourth invoice is 5000 USD.
Start Date: Determines start date for term to be applied thus if it is set as 01-MAR-2020 for a project which starts on 01-
JAN-2020 then there will not be any withholding amount for invoices which are generated for event or expenditure item
with date between 01-JAN-2020 to 29-FEB-2020.
End Date: Determines end date for term to be applied thus if it is set as 30-SEP-2020 for a project which ends on 31-
DEC-2020 then there will not be any withholding amount for invoices which are generated for event or expenditure item
with date between 01-OCT-2020 to 31-DEC-2020.
If requirement is to withhold amount for invoices based on expenditure type or expenditure category. Let’s say business
has a contract with customer to only withhold amount for labour transactions but not for material transactions for such
cases this type of withholding term is defined.
In this setup as well term can be defined based on Amount or Percentage. To add withholding term based on expenditure
category please follow below steps.
Expenditure Category: This determines source for expenditure. While creating expenditure item user has to select
expenditure type which belongs to expenditure category.
There can be multiple expenditure types exist for expenditure category. For example expenditure category could be
Construction Labour and there could be many expenditure types like Electrician - Labour, Carpenter- Labour and Field
Engineer- Labour could be expenditure types.
If user wants to withhold invoice amounts for all these above expenditure types then only expenditure category
information should be provided.
Let’s say in above example if business wants to withhold amount for invoices based on expenditure item created for
expenditure type Electrician – Labour then user has to provide expenditure type in the term setup as well. This is an
optional field.
Non-Labour Resources: As name suggests this is a resource with non-labour in nature thus if a requirement to withhold
amount based on some specific non-labour resource then this field need to be setup in term.
Other Fields Withholding Percentage, Withholding Amount, Threshold Amount, Start Date and End Date are explained in
previous section.
If requirement is to withhold amount for invoices based on event type or revenue category. Let’s say business has a
contract with customer to only withhold amount for fee revenue but not for payment revenue such cases withholding term
is defined based on revenue category.
In this type of term as well User has to choose either withholding percentage or withholding amount.
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 5/24
10/16/23, 6:09 PM Document Display
Revenue Category: This determines source for revenue. User can create events based on event type and each event
type belong to revenue category.
There can be multiple event types exist for revenue category. For example revenue category could be Sales and it can
have event types as Customer Deposit and Cost of Goods Sold.
If user wants to withhold invoice amounts for all these above event types then only revenue category information should
be provided.
Event Type: This is a classification of event which is created for generating invoice or revenue.
If business would like to withhold amount only for event type Customer Deposit then withholding term will be defined
based on event type and revenue category combination.
Other Fields Withholding Percentage, Withholding Amount, Threshold Amount, Start Date and End Date are explained in
“Withholding Terms” section.
Billing Term:
Billing term determines how invoices will be generated for already withheld amount in later stage of project or task.
Total Withheld Amount: If this method is used then user has to enter maximum amount for withheld amount and as
soon as that amount reaches then retention invoice will be generated.
Below fields are selected while defining billing term based on Total Withheld Amount.
Total Amount: This is the maximum amount until which retention invoice will not be generated. For example if Total
Amount is provided as 5000 USD then as soon as total withholding amount reaches 5000 USD then retention invoices will
start generating. Until total withholding amount is 5000 USD then retention invoice cannot be generated.
Bill Percentage: This determines how much percentage of withholding amount will be billed.
For example: If bill percentage is 20% then as soon as withholding amount reaches 5000 USD then 1000 USD (20% of
5000 USD) will be billed and delivered to customer.
For example: If bill amount is 2000 USD then as soon as withholding amount reaches 5000 USD then 2000 USD will be
billed and delivered to customer.
Percent Complete: If this method is used then retention invoice will start generating as soon as specified percentage of
project or task is completed.
Below fields are selected while defining billing term based on Percent Complete.
Percent Complete: This determines how much physical percentage of a project or task should be completed before
generating retention invoices.
Bill Percentage: This determines how much percentage of withholding amount will be billed.
Billing Cycle: If this method is used then retention invoice will be automatically generated based on cycle. Let’s say if
requirement is to generate retention invoice on monthly basis then billing term will be setup based on billing cycle.
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 6/24
10/16/23, 6:09 PM Document Display
Below fields are selected while defining billing term based on Percent Complete.
Cycle Name: This determines frequency of days on which retention invoice will be generated.
Bill Percentage: This determines how much percentage of withholding amount will be billed.
Client Extension: If there is a complex business logic involved in generating retention invoices then billing method is
selected as Client extension and custom logic can be written in package PA_CLIENT_EXTN_RETENTION procedure
BILL_RETENTION.
If business would like to account unbilled retention amount to a separate account then this setup is required. To enable
accounting for unbilled retention amount implementer has to enable “Account for Unbilled Retention” flag. To perform this
setup please follow below steps.
Once retention is defined even for one project in a specific operating unit then this flag for that operating unit cannot be
disabled.
To account Unbilled retention amount user has to setup Auto Accounting rule for function “Revenue and Invoice Accounts”
and function transaction “Unbilled Retention Account”.
If Account for Unbilled Retention flag is enabled then for the first invoice (revenue is not yet created) Unearned Revenue
Amount would be same as that of Total Invoice Amount. E.g. If you have created first billing event of $1000 and
withholding amount is $100 then Unearned Revenue Amount would be $1000.
However if Account for Unbilled Retention Amount flag is disabled then Unearned revenue amount would be same as
(Total Invoice Amount – Retention Amount). E.g. If you have created billing event of $1000 and withholding amount is
$100 then Unearned Revenue Amount would be $900.
Retention Format
Retention format is a type of invoice format, which is used for invoice lines created for withheld amounts.
Retention format should have a grouping as Retention and can have below columns.
1. Withholding Percentage/Amount
2. Withholding Term
3. Withholding Basis Amount
4. Invoice Processing Currency
5. Text
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 8/24
10/16/23, 6:09 PM Document Display
Retention billing format is a type of invoice format, which is used for invoice lines created for retention invoices.
Retention billing format should have a grouping as Retention Billing and can have below columns.
This is the value of retention billing method. For example if user selects Billing Cycle then method value would be Cycle
Name.
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 9/24
10/16/23, 6:09 PM Document Display
Retention Format and Retention Billing Format are assigned to the Project so that while generating invoice with
withholding amount and generating retention invoice, invoice lines can be formatted as per business requirement.
To assign retention format and retention billing format for project, please follow below steps.
Setup which has been done in previous section will be used. Here in this case process flow is shown for below test cases.
Please note Agreement, Funding and Revenue Budget need to be created before generating invoices.
Case 1:
Case 2:
Case 3:
1. Create event of amount 1200 USD with event type as Customer Deposit
2. Generate Invoice as per setup expected result will be invoice with amount 200 USD (1000 USD will be withheld)
Case 4:
1. Create event of amount 2000 USD with event date which is later than 31st Oct 2019
2. Generate Invoice as per setup expected result there will not be any withholding amount as term ends on 31st Oct
2019.
Enter Event
As mentioned above in this test case previous setups will be used. An event will be created with 1500 USD. To create event
follow below steps.
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 11/24
10/16/23, 6:09 PM Document Display
Expected result is 1 Invoice with two lines (1500 USD Standard and -300 USD Retention) will be generated.
Interface Invoice
To interface invoice to Receivable so that same can be forwarded to customer, below steps need to be followed up.
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 12/24
10/16/23, 6:09 PM Document Display
Another event will be created with 1500 USD. To create event follow below steps.
Generate Invoice
Now when PRC: Generate Draft Invoice for Single Project will run, there will be two invoices generated.
1. Invoice with two lines (1500 USD Standard and -300 USD Retention)
2. Another Retention Invoice with amount 300 USD (0.5* Total Withheld Amount)
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 13/24
10/16/23, 6:09 PM Document Display
Generate Invoice
Now when PRC: Generate Draft Invoice for Single Project will run, there will be two invoices generated.
1. Invoice with two lines (1500 USD Standard and -300 USD Retention)
2. Another Retention Invoice with amount 300 USD (0.5* Total Withheld Amount)
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 14/24
10/16/23, 6:09 PM Document Display
Same project will be considered for this case. To create expenditure please follow below steps.
Generate Invoice
To generate invoice for expenditure item, first user need to run request “PRC: Generate Draft Revenue for Single Project”
After request completion run request “PRC: Generate Draft Invoice for Single Project”
Expected result is 1 Invoice with two lines (400 USD Standard and -40 USD Retention) will be generated.
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 16/24
10/16/23, 6:09 PM Document Display
To validate retention term based on revenue category, In this case event will be created with specific event type “Customer
Deposit” with 1200 USD.
Generate Invoice
Expected result is 1 Invoice with two lines (1200 USD Standard and -1000 USD Retention) will be generated.
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 17/24
10/16/23, 6:09 PM Document Display
To validate retention term dates, In this case event will be created with event date as 01-NOV-2019 2000 USD.
Generate Invoice
Expected result is 1 Invoice with 1 line (2000 USD Standard and –there will not be any retention line) will be generated.
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 18/24
10/16/23, 6:09 PM Document Display
Technical Components
This section includes technical components used for retention billing functionality.
This section gives details of tables used to store retention billing details.
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 19/24
10/16/23, 6:09 PM Document Display
Tables
Stores
retention
PA_PROJ_RETN_RULES level and
term
information.
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 20/24
10/16/23, 6:09 PM Document Display
Stores
PA_PROJ_RETN_BILL_RULES billing term
information.
Stores
retention
amounts for
PA_PROJECT_RETENTIONS project
based on
retention
term.
Stores
retention
summary
PA_SUMMARY_PROJECT_RETN
information
based on
project
Stores
retention
PA_RETN_INVOICE_DETAILS
invoice
details.
Client Extension
This section gives detail on client extension used for retention billing.
Client Extension
This
extension
will be
called
only if the
billing
method is
chosen as
'Client
Extension'
in the
retention
PA_CLIENT_EXTN_RETENTION
setup for
a
customer,
project
and top
task.
Retention
Billing
Logic can
be added
here.
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 21/24
10/16/23, 6:09 PM Document Display
Issues
Issues
steps to
Issue cause solution
reproduce
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 22/24
10/16/23, 6:09 PM Document Display
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 23/24
10/16/23, 6:09 PM Document Display
6. No
item is
appearing in
LOV
Q1. How can retention be applied to a project invoice after the Tax is applied to the invoice?
Retention is applied for project invoice at project billing level based on retention setup at project level whereas tax on
invoice calculated in Receivables after invoice gets interfaced from Project Billing thus through standard application it’s not
possible to apply retention on project invoice after tax application.
Q2. How retention amount is calculated for credit memo if retention term is defined based on amount?
Credit memos have negative amount and as per retention billing functionality if retention term is defined based on amount
then any invoice generated until that amount will be withheld thus entire credit memo amount will be withheld since
negative amount will be lesser than withholding amount defined at retention setup.
NOTE:
In the images above and/or the attached document, user details / company name / address / email / telephone
number represent a fictitious sample (based upon made up data used in the Oracle Demo Vision instance).
Any similarity to actual persons, living or dead, is purely coincidental and not intended in any manner.
https://support.oracle.com/epmos/faces/SearchDocDisplay?_adf.ctrl-state=m27jss2dn_132#aref_section38 24/24