This document outlines the specifications and the methodology for using the various Revenue Adjustment APIs. These APIs provide an extension to existing functionality of adjusting revenue and sales credits through the standard AR Revenue Management form.
You can access these APIs:
As standard PL/SQL servers-side routine calls
Through Forms, utilizing the capability of Forms6 to have a procedure as its underlying base table
The Revenue Adjustment API addresses the following basic functionality via different API calls:
Unearning revenue
Earning revenue
Transferring sales credits between salespersons
Adding new non-revenue sales credits
Presently, the main business need for the API is the requirement to have event-based revenue recognition. In Receivables, you can defer revenue recognition, and earn the revenue at a later date using the API. Throughout the process, the API uses AutoAccounting to determine the accounts to be debited/credited with each operation.
To earn and unearn revenue, transfer sales credits, and add non-revenue sales credits at the transaction, item, category, or transaction line level, you can call the following four PL/SQL APIs:
AR_RevenueAdjust_PUB.Unearn_Revenue: Transfers the specified amount of revenue from the revenue account to the unearned revenue account on the specified transaction lines.
AR_RevenueAdjust_PUB.Earn_Revenue: Transfers the specified amount of revenue from the unearned revenue account to the revenue account on the specified transaction lines.
AR_RevenueAdjust_PUB.Transfer_Sales_Credits: Transfers revenue and/or non-revenue sales credits between salespersons on the specified transaction lines. In the case of revenue sales credits, the associated revenue is also transferred between cost centers, assuming that AutoAccounting derives the cost center segment of the accounting flexfield from the salesperson.
AR_RevenueAdjust_PUB.Add_Non_Revenue_Sales_Credits: Adds non-revenue sales credits for any salesperson to the specified transaction lines.
AR_Revenueadjust_PUB.Record_Customer_Acceptance: Removes customer acceptance contingencies and enables revenue recognition.
AR_Revenueadjust_PUB.Update_Contingency_Expirations: Updates the expiration date and period for specific time-based contingencies.
For all options, a specific amount or percentage of the total value can be specified. All available revenue can also be specified, except for Add_Non_Revenue_Sales_Credits, where this is not applicable.
Note: You cannot specify both revenue and nonrevenue sales credits when passing sales group information to the above APIs.
Call this routine to move revenue from the earned revenue account to the unearned revenue account using AutoAccounting. This API routine has 4 input and 5 output parameters in total. One of the input parameters is a record type that holds all the revenue adjustment information and has 120 elements. The output parameters include the revenue_adjustment_number and revenue_adjustment_id of the revenue adjustment.
The following is the breakdown of the parameters:
Standard API parameters: 3
Revenue Adjustment parameters: 1 (revenue adjustment record type)
Standard API parameters: 3
Revenue Adjustment parameters: 2
The input revenue adjustment parameter is a record of type AR_Revenue_Adjustment_PVT.Rev_Adj_Rec_Type.
TYPE Rev_Adj_Rec_Type IS RECORD
(CUSTOMER_TRX_ID NUMBER(15)
,TRX_NUMBER RA_CUSTOMER_TRX.trx_number%TYPE
,BATCH_SOURCE_NAME RA_BATCH_SOURCES.name%TYPE
,ADJUSTMENT_TYPE VARCHAR2(15) DEFAULT 'UN'
,FROM_SALESREP_ID NUMBER(15)
,FROM_SALESREP_NUMBER RA_SALESREPS.salesrep_number%TYPE
,TO_SALESREP_ID NUMBER(15)
,TO_SALESREP_NUMBER RA_SALESREPS.salesrep_number%TYPE
,FROM_SALESGROUP_ID jtf_rs_groups_b.group_id%TYPE
,TO_SALESGROUP_ID jtf_rs_groups_b.group_id%TYPE
,SALES_CREDIT_TYPE VARCHAR2(15) DEFAULT 'R'
,AMOUNT_MODE VARCHAR2(15) DEFAULT 'T'
,AMOUNT NUMBER
,PERCENT NUMBER
,LINE_SELECTION_MODE VARCHAR2(15) DEFAULT 'A'
,FROM_CATEGORY_ID NUMBER(15)
,FROM_CATEGORY_SEGMENT1 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT2 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT3 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT4 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT5 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT6 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT7 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT8 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT9 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT10 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT11 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT12 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT13 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT14 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT15 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT16 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT17 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT18 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT19 VARCHAR2(40)
,FROM_CATEGORY_SEGMENT20 VARCHAR2(40)
,TO_CATEGORY_ID NUMBER(15)
,TO_CATEGORY_SEGMENT1 VARCHAR2(40)
,TO_CATEGORY_SEGMENT2 VARCHAR2(40)
,TO_CATEGORY_SEGMENT3 VARCHAR2(40)
,TO_CATEGORY_SEGMENT4 VARCHAR2(40)
,TO_CATEGORY_SEGMENT5 VARCHAR2(40)
,TO_CATEGORY_SEGMENT6 VARCHAR2(40)
,TO_CATEGORY_SEGMENT7 VARCHAR2(40)
,TO_CATEGORY_SEGMENT8 VARCHAR2(40)
,TO_CATEGORY_SEGMENT9 VARCHAR2(40)
,TO_CATEGORY_SEGMENT10 VARCHAR2(40)
,TO_CATEGORY_SEGMENT11 VARCHAR2(40)
,TO_CATEGORY_SEGMENT12 VARCHAR2(40)
,TO_CATEGORY_SEGMENT13 VARCHAR2(40)
,TO_CATEGORY_SEGMENT14 VARCHAR2(40)
,TO_CATEGORY_SEGMENT15 VARCHAR2(40)
,TO_CATEGORY_SEGMENT16 VARCHAR2(40)
,TO_CATEGORY_SEGMENT17 VARCHAR2(40)
,TO_CATEGORY_SEGMENT18 VARCHAR2(40)
,TO_CATEGORY_SEGMENT19 VARCHAR2(40)
,TO_CATEGORY_SEGMENT20 VARCHAR2(40)
,FROM_INVENTORY_ITEM_ID NUMBER(15)
,FROM_ITEM_SEGMENT1 VARCHAR2(40)
,FROM_ITEM_SEGMENT2 VARCHAR2(40)
,FROM_ITEM_SEGMENT3 VARCHAR2(40)
,FROM_ITEM_SEGMENT4 VARCHAR2(40)
,FROM_ITEM_SEGMENT5 VARCHAR2(40)
,FROM_ITEM_SEGMENT6 VARCHAR2(40)
,FROM_ITEM_SEGMENT7 VARCHAR2(40)
,FROM_ITEM_SEGMENT8 VARCHAR2(40)
,FROM_ITEM_SEGMENT9 VARCHAR2(40)
,FROM_ITEM_SEGMENT10 VARCHAR2(40)
,FROM_ITEM_SEGMENT11 VARCHAR2(40)
,FROM_ITEM_SEGMENT12 VARCHAR2(40)
,FROM_ITEM_SEGMENT13 VARCHAR2(40)
,FROM_ITEM_SEGMENT14 VARCHAR2(40)
,FROM_ITEM_SEGMENT15 VARCHAR2(40)
,FROM_ITEM_SEGMENT16 VARCHAR2(40)
,FROM_ITEM_SEGMENT17 VARCHAR2(40)
,FROM_ITEM_SEGMENT18 VARCHAR2(40)
,FROM_ITEM_SEGMENT19 VARCHAR2(40)
,FROM_ITEM_SEGMENT20 VARCHAR2(40)
,TO_INVENTORY_ITEM_ID NUMBER(15)
,TO_ITEM_SEGMENT1 VARCHAR2(40)
,TO_ITEM_SEGMENT2 VARCHAR2(40)
,TO_ITEM_SEGMENT3 VARCHAR2(40)
,TO_ITEM_SEGMENT4 VARCHAR2(40)
,TO_ITEM_SEGMENT5 VARCHAR2(40)
,TO_ITEM_SEGMENT6 VARCHAR2(40)
,TO_ITEM_SEGMENT7 VARCHAR2(40)
,TO_ITEM_SEGMENT8 VARCHAR2(40)
,TO_ITEM_SEGMENT9 VARCHAR2(40)
,TO_ITEM_SEGMENT10 VARCHAR2(40)
,TO_ITEM_SEGMENT11 VARCHAR2(40)
,TO_ITEM_SEGMENT12 VARCHAR2(40)
,TO_ITEM_SEGMENT13 VARCHAR2(40)
,TO_ITEM_SEGMENT14 VARCHAR2(40)
,TO_ITEM_SEGMENT15 VARCHAR2(40)
,TO_ITEM_SEGMENT16 VARCHAR2(40)
,TO_ITEM_SEGMENT17 VARCHAR2(40)
,TO_ITEM_SEGMENT18 VARCHAR2(40)
,TO_ITEM_SEGMENT19 VARCHAR2(40)
,TO_ITEM_SEGMENT20 VARCHAR2(40)
,FROM_CUST_TRX_LINE_ID NUMBER(15)
,FROM_LINE_NUMBER NUMBER(15)
,TO_CUST_TRX_LINE_ID NUMBER(15)
,TO_LINE_NUMBER NUMBER(15)
,GL_DATE DATE
,REASON_CODE VARCHAR2(15)
,COMMENTS VARCHAR2(2000)
,ATTRIBUTE_CATEGORY VARCHAR2(30)
,ATTRIBUTE1 VARCHAR2(150)
,ATTRIBUTE2 VARCHAR2(150)
,ATTRIBUTE3 VARCHAR2(150)
,ATTRIBUTE4 VARCHAR2(150)
,ATTRIBUTE5 VARCHAR2(150)
,ATTRIBUTE6 VARCHAR2(150)
,ATTRIBUTE7 VARCHAR2(150)
,ATTRIBUTE8 VARCHAR2(150)
,ATTRIBUTE9 VARCHAR2(150)
,ATTRIBUTE10 VARCHAR2(150)
,ATTRIBUTE11 VARCHAR2(150)
,ATTRIBUTE12 VARCHAR2(150)
,ATTRIBUTE13 VARCHAR2(150)
,ATTRIBUTE14 VARCHAR2(150)
,ATTRIBUTE15 VARCHAR2(150));
The following table lists standard API parameters that are common to all the routines in the Revenue Adjustment API.
| Parameter | Type | Data-type | Required | Default Value | Description |
|---|---|---|---|---|---|
| p_api_version | IN | NUMBER | Yes | Used to compare version numbers of incoming calls to its current version number. Unexpected error is raised if version incompatibility exists. In the current version of the API, you should pass in a value of 1.0 for this parameter. | |
| p_init_msg_list | IN | VARCHAR2 | FND_API.G_FALSE | Allows API callers to request that the API does initialization of the message list on their behalf. | |
| p_commit | IN | VARCHAR2 | FND_API.G_FALSE | Used by API callers to ask the API to commit on their behalf. | |
| p_rev_adj_rec | IN | AR_Revenue_Adjustment_PVT.Rev_Adj_Rec_Type | Yes | See break- down below for individual elements | Revenue Adjustment record type |
| x_return_status | OUT | VARCHAR2 | Represents the API overall return status. Detailed in Return Status. | ||
| x_msg_count | OUT | NUMBER | Number of messages in the API message list. | ||
| x_msg_data | OUT | VARCHAR2 | This is the message in encoded format if x_msg_count=1. | ||
| x_adjustment_id | OUT | NUMBER | The ID of the resulting revenue adjustment. | ||
| x_adjustment_number | OUT | VARCHAR2 | The user visible number of the resulting revenue adjustment. |
The following table lists Rev_Adj_Rec_Type elements that are relevant to Unearn_Revenue:
Note: If required parameters are not passed in a call to this API, then the call will fail. However, depending on the business scenario, you will have to pass in values for other parameters to successfully create the business object. Otherwise, error messages will be reported.
At least one of the numbered sets of parameters is required.
| Parameter | Data-type | Required | Description |
|---|---|---|---|
| p_customer_trx_id | NUMBER(15) | 1 | The ID of the transaction on which revenue is to be adjusted. Default: None Validation: Must exist if specified. Must not have a class of 'CB','DM','BR','DEP','GUAR' (i.e. chargeback, debit memo, bills receivable, deposit, guarantee). Must not have had credit memo(s) raised against the full transaction value. Warning if partial credit memo has been raised. Every line must have revenue sales credits adding to 100%. Errors: AR_TAPI_TRANS_NOT_EXIST AR_TW_INCORRECT_SALESCREDIT AR_RA_CB_DISALLOWED AR_RA_DM_DISALLOWED AR_RA_BR_DISALLOWED AR_RA_DEP_DISALLOWED AR_RA_GUAR_DISALLOWED AR_TW_INCORRECT_SALESCREDIT AR_RA_FULL_CREDIT Warnings: AR_RA_PARTIAL_CREDIT |
| trx_number | ra_customer_trx.trx_number%TYPE | 1 | The user visible transaction number Default: None Validation: Ignored if customer_trx_id has a value. Must be unique. Batch source can be optionally passed as extra assurance of uniqueness - then must be unique for that batch source. Otherwise, validation is the same as for customer_trx_id. Errors: AR_RA_TRX_NOTFOUND AR_RA_TRX_TOO_MANY_ROWS |
| batch_source_name | ra_batch_sources.name%TYPE | Name of the batch source associated with the trx_number, if specified. Only used in association with trx_number to help ensure uniqueness. Default: None Validation: Ignored if trx_number is not passed. If an invalid string is passed, the trx not found message will result. |
|
| adjustment_type | VARCHAR2(15) | Type of revenue adjustment. This element should be left null. Default: 'UN' |
|
| from_salesrep_id | NUMBER(15) | The ID of the salesperson whose revenue is being adjusted. Validation: If specified, must exist, must be currently active, and must have been active on transaction date. Must have revenue sales credits on at least one line on the transaction. Error: AR_TAPI_INVALID_SALESREP_ID AR_RA_SALESREP_NOT_ON_TRX |
|
| from_salesrep_number | ra_salesreps.salesrep_number%TYPE | The user visible number of the salesperson whose revenue is being adjusted. Validation: Ignored if from_salesrep_id is specified. Otherwise, validation is as for from_salesrep_id. Error: AR_RA_INAVLID_SALESREP_NUMBER |
|
| to_salesrep_id | NUMBER | Not used for unearning revenue and should be left null. | |
| to_salesrep_number | VARCHAR2(30) | Not used for unearning revenue and should be left null. | |
| from_salesgroup_id | jtf_rs_groups_b. group_id%TYPE | The ID of the sales group of the salesperson whose revenue is being adjusted. Validation: Must have revenue sales credits on at least one line on the transaction. Error: AR_RA_SALESREP_NOT_ON_TRX |
|
| to_salesgroup_id | jtf_rs_groups_b. group_id%TYPE | Not used for unearning revenue and should be left null. | |
| sales_credit_type | VARCHAR2(15) | Not used for unearning revenue and should be left null. | |
| amount_mode | VARCHAR2(15) | The amount mode specifies whether an amount, a percentage (of total value of selected lines), or all adjustable revenue is to be adjusted. Possible values are:
Default: 'T' Validation: Must be one of the above values Error: AR_RA_INVALID_AMOUNT_MODE |
|
| amount | NUMBER | The amount of revenue to be adjusted Default: None Validation: Ignored unless amount_mode = 'A', in which case it must have a value. Must be =< total recognized revenue for selected lines, and salesperson (if specified). Errors: AR_RA_AMT_EXCEEDS_AVAIL_REV AR_RA_ZERO_AMOUNT |
|
| percent | NUMBER | The percentage of total selected transaction line value to be adjusted. Default: None Validation: Ignored unless amount_mode = 'P' in which case it must have a value. Must be =< percentage of total value of selected lines represented by recognized revenue for selected lines, and salesperson (if specified). Errors: AR_RA_PCT_EXCEEDS_AVAIL_PCT AR_RA_ZERO_AMOUNT |
|
| line_selection_mode | VARCHAR2(15) | The line selection mode determines how lines were selected for adjustment. Possible values are:
Default: 'A' Validation: Must be one of the above values Error: AR_RA_INVALID_LINE_MODE |
|
| from_category_id | NUMBER(15) | The ID of the item category used to identify the lines to be adjusted. Default: None Validation: Must be a valid category ID, and there must be lines on the transaction that have items belonging to this category. Must be specified if line selection mode = 'C'. Errors: AR_RA_NO_FROM_CATEGORY AR_RA_INVALID_CATEGORY_ID AR_RA_CATEGORY_NOT_ON_TRX |
|
| from_category_segment1 -from_category_segment20 | VARCHAR2(40) | Segments 1 to 20 of the category flexfield Default: None Validation: Ignored if from_category_id has a value. Enough segment values to uniquely identify a category must be passed - ideally all defined segments. Otherwise, validation is the same as for from_category_id. Error: AR_RA_INVALID_CAT_SEGMENTS |
|
| to_category_id | NUMBER(15) | Not currently used and should be left null. | |
| to_category_segment1 -to_category_segment20 | VARCHAR2(40) | Not currently used and should be left null. | |
| from_inventory_item_id | NUMBER(15) | The ID of the inventory item used to identify the lines to be adjusted. Default: None Validation: Must be a valid inventory item ID and there must be lines on the transaction that have items with this ID. Must be specified if line selection mode = 'I'. Errors: AR_RA_NO_FROM_ITEM AR_RA_INVALID_ITEM_ID AR_RA_ITEM_NOT_ON_TRX |
|
| from_item_segment1 -from_item_segment20 | VARCHAR2(40) | Segments 1 to 20 of the item flexfield Default: None Validation: Ignored if from_inventory_item_id has a value. Enough segment values to uniquely identify an item must be passed - ideally all defined segments. Otherwise, validation is the same as for from_inventory_item_id. Error: AR_RA_INVALID_ITEM_SEGMENTS |
|
| to_inventory_item_id | NUMBER(15) | Not currently used and should be left null. | |
| to_item_segment1 -to_item_segment20 | VARCHAR2(40) | Not currently used and should be left null. | |
| from_cust_trx_line_id | NUMBER(15) | The ID of the transaction line to be adjusted. Default: None Validation: Must be a valid line ID on the transaction. Must be specified if line selection mode = 'S' and from_line_number is null. Errors: AR_RA_NO_FROM_LINE AR_RA_INVALID_LINE_ID |
|
| from_line_number | NUMBER(15) | The user visible transaction line number. Default: None Validation: Ignored if from_cust_trx_line_id has a value. Must be a valid line number on the transaction. Errors: AR_RA_NO_FROM_LINE AR_RA_LINE_NOT_ON_TRX |
|
| gl_date | DATE | Date that adjusted revenue will be posted to the general ledger if revenue is recognized immediately. Start date of revenue recognition if revenue is deferred. Default: Gets defaulted to the current date if it is a valid gl_date. Validation: Ignored for lines that have non-deferred accounting rules AND a duration > 1. It is valid if the following conditions are true:
If the date passed is not valid, then a warning message is written to the stack and the date is automatically overridden with a valid date using the default:
Warning: AR_RA_GL_DATE_CHANGED |
|
| reason_code | VARCHAR2(15) | Yes | Lookup code for revenue adjustment reason Default: None Validation: Must be defined under AR lookup type 'REV_ADJ_REASON' Error: AR_RA_INVALID_REASON_CODE |
| comments | VARCHAR2 (2000) | Free text Default: None Validation: None |
|
| attribute_category | VARCHAR2(30) | Context of the revenue adjustment descriptive flexfield. Default: None Validation: None |
|
| attribute1 - attribute15 | VARCHAR2(150) | Attributes of the revenue adjustment descriptive flexfield Default: None Validation: Standard descriptive flexfield validation |
Objective:
To unearn all revenue on a transaction using a call to AR_RevenueAdjust_PUB.Unearn_Revenue and passing a minimum number of input parameters.
This table lists the entered parameters:
| Parameter | Entered Value | Default Value |
|---|---|---|
| p_api_version | 2.0 | |
| p_init_msg_list | FND_API.G_TRUE | |
| p_rev_adj_rec.trx_number | 'test_api_1' | |
| p_rev_adj_rec.reason_code | 'RA' |
This table lists the defaulted input parameters, which were not entered:
| Parameter | Entered Value | Default Value |
|---|---|---|
| p_rev_adj_rec.amount_mode | 'T' | |
| p_rev_adj_rec.line_selection_mode | 'A' | |
| p_rev_adj_rec.gl_date | SYSDATE |
The API call in this case would be:
AR_RevenueAdjust_PUB.Unearn_Revenue(
p_api_version => 2.0,
p_init_msg_list => FND_API.G_TRUE,
p_rev_adj_rec.trx_number => ‘test_api_1',
p_rev_adj_rec.reason_code => ‘RA',
x_return_status => l_return_status,
x_msg_count => l_msg_count,
x_msg_data => l_msg_data,
x_adjustment_id => l_adjustment_id,
x_adjustment_number => l_adjustment_number);
After execution of this API, the calling program retrieves the warnings and the error messages, put on the message stack by the API, in the following manner:
The warnings and the error messages put on the message stack by the API are retrieved after the execution of this API by the calling program, in the following manner:
IF l_msg_count = 1 Then
--there is one message raised by the API, so it has been sent out
--in the parameter x_msg_data, get it.
l_msg_data_out := l_msg_data;
ELSIF l_msg_count > 1 Then
--the messages on the stack are more than one so call them in a loop
-- and put the messages in a PL/SQL table.
loop
count := count +1 ;
l_mesg := FND_MSG_PUB.Get;
If l_mesg IS NULL Then
EXIT;
else
Mesg_tbl(count).message := l_mesg;
End if;
end loop;
END IF;
Depending on the message level threshold set by the profile option FND_API_MSG_LEVEL_THRESHOLD, the messages put on the message stack may contain both the error messages and the warnings.
Result:
All revenue on this transaction was unearned by specifying only four input parameters in the call to this API.
Call this routine to move revenue from the unearned revenue account to the earned revenue account using AutoAccounting. This API routine has 4 input and 5 output parameters in total and is almost exactly the same as the Unearn_Revenue routine described above in AR_RevenueAdjust_PUB.Unearn_Revenue.
The following is the breakdown of the parameters:
Standard API parameters: 3
Revenue Adjustment parameters: 1 (revenue adjustment record type)
Standard API parameters: 3
Revenue Adjustment parameters: 2
For a description of this routine's standard parameters, see AR_RevenueAdjust_PUB.Unearn_Revenue.
The Rev_Adj_Rec_Type elements that are relevant to Earn_Revenue are exactly the same as already listed in AR_RevenueAdjust_PUB.Unearn_Revenue, with the following exceptions listed in this table:
| Parameter | Data-type | Required | Description |
|---|---|---|---|
| to_salesrep_id | NUMBER | Not used for earning revenue and should be left null. | |
| to_salesrep_number | VARCHAR2 | Not used for earning revenue and should be left null. | |
| to_salesgroup_id | jtf_rs_groups_b. group_id%TYPE | Not used for earning revenue and should be left null. | |
| sales_credit_type | VARCHAR2(15) | Not used for earning revenue and should be left null. |
Objective:
To earn all revenue on a transaction using a call to AR_RevenueAdjust_PUB.Earn_Revenue and passing a minimum number of input parameters.
This table lists the entered parameters:
| Parameter | Entered Value | Default Value |
|---|---|---|
| p_api_version | 2.0 | |
| p_init_msg_list | FND_API.G_TRUE | |
| p_rev_adj_rec.trx_number | 'test_api_1' | |
| p_rev_adj_rec.reason_code | 'RA' |
This table lists the defaulted input parameters, which were not entered:
| Parameter | Entered Value | Default Value |
|---|---|---|
| p_rev_adj_rec.amount_mode | 'T' | |
| p_rev_adj_rec.line_selection_mode | 'A' | |
| p_rev_adj_rec.gl_date | SYSDATE |
The API call in this case would be:
AR_RevenueAdjust_PUB.Earn_Revenue(
p_api_version => 2.0,
p_init_msg_list => FND_API.G_TRUE,
p_rev_adj_rec.trx_number => 'test_api_1',
p_rev_adj_rec.reason_code => 'RA',
x_return_status => l_return_status,
x_msg_count => l_msg_count,
x_msg_data => l_msg_data,
x_adjustment_id => l_adjustment_id,
x_adjustment_number => l_adjustment_number);
The warnings and the error messages put on the message stack by the API are retrieved after the execution of this API by the calling program, as described in Example.
Result:
All revenue on this transaction was earned by specifying only four input parameters in the call to this API.
Call this routine to transfer sales credits from any salesperson with sales credits on the transaction to any other salesperson. In addition, if revenue sales credits are transferred, then the associated revenue is transferred between cost centers if the AutoAccounting rules call the salesperson table and the cost center segment is derived from the salesperson.
This API routine has 4 input and 5 output parameters in total and is similar to the Unearn_Revenue routine described above in AR_RevenueAdjust_PUB.Unearn_Revenue. The following is the breakdown of the parameters:
Standard API parameters: 3
Revenue Adjustment parameters: 1 (revenue adjustment record type)
Standard API parameters: 3
Revenue Adjustment parameters: 2
For a description of this routine's standard parameters, see AR_RevenueAdjust_PUB.Unearn_Revenue.
The Rev_Adj_Rec_Type elements that are relevant to Transfer_Sales_Credits are the same as already listed in AR_RevenueAdjust_PUB.Unearn_Revenue, with the following exceptions/additions listed in this table.
Note: If required parameters are not passed in a call to this API, then the call will fail. However, depending on the business scenario, you will have to pass in values for other parameters to successfully create the business object. Otherwise, error messages will be reported.
| Parameter | Data-type | Required | Description |
|---|---|---|---|
| p_customer_trx_id | NUMBER(15) | 1 | The ID of the transaction on which sales credits are to be adjusted. Default: None Validation: Must exist if specified. Must not have a class of 'CB','BR','GUAR' (i.e. chargeback, bills receivable, guarantee). Must not have had credit memo(s) raised against the full transaction value. Warning if partial credit memo has been raised. Every line must have revenue sales credits adding to 100%. Errors: AR_TAPI_TRANS_NOT_EXIST AR_TW_INCORRECT_SALESCREDIT AR_RA_CB_DISALLOWED AR_RA_BR_DISALLOWED AR_RA_GUAR_DISALLOWED AR_TW_INCORRECT_SALESCREDIT AR_RA_FULL_CREDIT Warnings: AR_RA_PARTIAL_CREDIT |
| from_salesrep_id | NUMBER(15) | The ID of the salesperson from whom sales credits are being transferred. Default: Null Validation: If specified, must exist, must be currently active, and must have been active on transaction date. Must have revenue sales credits on at least one line on the transaction. If neither from_salesrep_id nor from_salesrep_number are specified, sales credits of the specified type are transferred belonging to all salesreps on the transaction (i.e. null = all). Error: AR_TAPI_INVALID_SALESREP_ID AR_RA_SALESREP_NOT_ON_TRX |
|
| from_salesrep_number | ra_salesreps.salesrep_number%TYPE | The user visible number of the salesperson from whom sales credits are being transferred. Validation: Ignored if from_salesrep_id is specified. Otherwise, validation is as for from_salesrep_id. Error: AR_RA_INVALID_SALESREP_NUMBER |
|
| to_salesrep_id | NUMBER(15) | 2 | The ID of the salesperson to whom sales credits are being transferred. Validation: If specified, must exist, and must be currently active and must have been active on transaction date. Errors: AR_TAPI_INVALID_SALESREP_ID AR_RA_NO_TO_SALESREP |
| to_salesrep_number | ra_salesreps.salesrep_number%TYPE | 2 | The user visible number of the salesperson to whom sales credits are being transferred. Validation: Ignored if to_salesrep_id is specified. Otherwise, validation is as for to_salesrep_id. Error: AR_RA_INVALID_SALESREP_NUMBER |
| from_salesgroup_id | jtf_rs_groups_b. group_id%TYPE | The ID of the sales group of the salesperson from whom sales credits are being transferred. Default: Null Validation: Must have sales credits (of the type being transferred) on at least one line on the transaction. If FROM_SALESGROUP_ID is not specified, then all sales credits of the specified type for the chosen salesperson are transferred (ie. null = all). Error: AR_RA_SALESREP_NOT_ON_TRX |
|
| to_salesgroup_id | jtf_rs_groups_b.group_id%TYPE | The ID of the sales group of the salesperson to whom sales credits are being transferred. Validation: If specified, then must exist and must be currently active. Salesperson must have been an active member of this group at some time between:
Error: AR_INVALID_SALESGROUP_ID |
|
| sales_credit_type | VARCHAR2(15) | Yes | The type of sales credit being transferred. Possible values:
Default: 'R' Validation: Must be one of the above values. Note: The value B cannot be used if either FROM_SALESGROUP_ID or TO_SALESGROUP_ID is specified. Error: AR_INCOMPATIBLE_CREDIT_TYPE AR_RA_INVALID_SALESCRED_TYPE |
Objective:
To transfer all revenue sales credits on a transaction from a salesperson to a new salesperson using a call to AR_RevenueAdjust_PUB.Transfer_Sales_Credits and passing a minimum number of input parameters.
This table lists the entered parameters:
| Parameter | Entered Value | Default Value |
|---|---|---|
| p_api_version | 2.0 | |
| p_init_msg_list | FND_API.G_TRUE | |
| p_rev_adj_rec.trx_number | 'test_api_1' | |
| p_rev_adj_rec.from_salesrep_number | '101' | |
| p_rev_adj_rec.to_salesrep_number | '299' | |
| p_rev_adj_rec.reason_code | 'RA' |
This table lists the defaulted input parameters, which were not entered:
| Parameter | Entered Value | Default Value |
|---|---|---|
| p_rev_adj_rec.amount_mode | 'T' | |
| p_rev_adj_rec.sales_credit_type | 'R' | |
| p_rev_adj_rec.line_selection_mode | 'A' | |
| p_rev_adj_rec.gl_date | SYSDATE |
The API call in this case would be:
AR_RevenueAdjust_PUB.Transfer_Sales_Credits(
p_api_version => 2.0,
p_init_msg_list => FND_API.G_TRUE,
p_rev_adj_rec.trx_number => 'test_api_1',
p_rev_adj_rec.from_salesrep_number => '101',
p_rev_adj_rec.to_salesrep_number => '299'
p_rev_adj_rec.reason_code => 'RA',
x_return_status => l_return_status,
x_msg_count => l_msg_count,
x_msg_data => l_msg_data,
x_adjustment_id => l_adjustment_id,
x_adjustment_number => l_adjustment_number);
The warnings and the error messages put on the message stack by the API are retrieved after execution of this API by the calling program, as described in Example.
Result:
All revenue sales credits on this transaction belonging to salesperson 101 were transferred to salesperson 299 by specifying only six input parameters in the call to this API. Additionally, all associated revenue was transferred between corresponding cost centers. Note that if salesrep number 101 was the only salesperson with revenue sales credits on this transaction, then from_salesrep_number could have been omitted. This is because no specified salesperson means all salespersons, thereby cutting the required number of parameters to five.
Call this routine to add non-revenue sales credits to any existing or new salesperson on a transaction. This does not involve a transfer of revenue. This API routine has 4 input and 5 output parameters in total and is similar to the Unearn_Revenue routine described in AR_RevenueAdjust_PUB.Unearn_Revenue.
The following is the breakdown of the parameters:
Standard API parameters: 3
Revenue Adjustment parameters: 1 (revenue adjustment record type)
Standard API parameters: 3
Revenue Adjustment parameters: 2
For a description of this routine's standard parameters, see AR_RevenueAdjust_PUB.Unearn_Revenue.
The Rev_Adj_Rec_Type elements that are relevant to Add_Non_Revenue_Sales_Credits are the same as already listed in AR_RevenueAdjust_PUB.Unearn_Revenue, with the following exceptions/additions listed in this table:
Note: If required parameters are not passed in a call to this API, then the call will fail. However, depending on the business scenario, you will have to pass in values for other parameters to successfully create the business object. Otherwise, error messages will be reported.
At least one of the numbered sets of parameters is required.
| Parameter | Data-type | Required | Description |
|---|---|---|---|
| p_customer_trx_id | NUMBER(15) | 1 | The ID of the transaction on which sales credits are to be adjusted. Default: None Validation: Must exist if specified. Must not have a class of 'CB','BR','GUAR' (i.e. chargeback, bills receivable, guarantee). Must not have had credit memo(s) raised against the full transaction value. Warning if partial credit memo has been raised. Every line must have revenue sales credits adding to 100%. Errors: AR_TAPI_TRANS_NOT_EXIST AR_TW_INCORRECT_SALESCREDIT AR_RA_CB_DISALLOWED AR_RA_BR_DISALLOWED AR_RA_GUAR_DISALLOWED AR_TW_INCORRECT_SALESCREDIT AR_RA_FULL_CREDIT Warnings: AR_RA_PARTIAL_CREDIT |
| from_salesrep_id | NUMBER(15) | Not applicable in this context and should be left null. | |
| from_salesrep_number | ra_salesreps.salesrep_number%TYPE | Not applicable in this context and should be left null. | |
| to_salesrep_id | NUMBER(15) | 2 | The ID of the salesperson to whom non-revenue sales credits are being added. Validation: If specified, must exist, and must be currently active and must have been active on transaction date. Errors: AR_TAPI_INVALID_SALESREP_ID AR_RA_NO_TO_SALESREP |
| to_salesrep_number | ra_salesreps.salesrep_number%TYPE | 2 | The user visible number of the salesperson to whom sales credits are being transferred. Validation: Ignored if to_salesrep_id is specified. Otherwise, validation is as for to_salesrep_id. Error: AR_RA_INVALID_SALESREP_NUMBER |
| from_salesgroup_id | jtf_rs_groups_b.group_id%TYPE | Not applicable in this context and should be left null. | |
| to_salesgroup_id | jtf_rs_groups_b.group_id%TYPE | The ID of the sales group of the salesperson to whom nonrevenue sales credits are being added. Validation: If specified, then must exist and must be currently active. Salesperson must have been an active member of this group at some time between:
Error: AR_INVALID_SALESGROUP_ID |
|
| sales_credit_type | VARCHAR2(15) | Not applicable in this context and should be left null. | |
| amount_mode | VARCHAR2(15) | The amount mode specifies whether an amount, a percentage (of total value of selected lines) is to be adjusted. Possible values are:
Default: 'T', or all adjustable revenue is not applicable in this context. Validation: Must be one of the above values (A or P). Error: AR_RA_INVALID_AMOUNT_MODE |
Objective:
To add 50% of the total transaction value in non-revenue sales credits to a new salesperson on a transaction, using a call to AR_RevenueAdjust_PUB.Add_Non_Revenue_Sales_Credits and passing a minimum number of input parameters.
This table lists the entered parameters:
| Parameter | Entered Value | Default Value |
|---|---|---|
| p_api_version | 2.0 | |
| p_init_msg_list | FND_API.G_TRUE | |
| p_rev_adj_rec.trx_number | 'test_api_1' | |
| p_rev_adj_rec.to_salesrep_number | '299' | |
| p_rev_adj_rec.amount_mode | 'P' | |
| p_rev_adj_rec.percent | 50 | |
| p_rev_adj_rec.reason_code | 'RA' |
This table lists the defaulted input parameters, which were not entered:
| Parameter | Entered Value | Default Value |
|---|---|---|
| p_rev_adj_rec.line_selection_mode | 'A' | |
| p_rev_adj_rec.gl_date | SYSDATE |
The API call in this case would be:
AR_RevenueAdjust_PUB.Add_Non_Revenue_Sales_Credits(
p_api_version => 2.0,
p_init_msg_list => FND_API.G_TRUE,
p_rev_adj_rec.trx_number => 'test_api_1',
p_rev_adj_rec.to_salesrep_number => '299'
p_rev_adj_rec.amount_mode => 'P',
p_rev_adj_rec.percent => 50,
p_rev_adj_rec.reason_code => 'RA',
x_return_status => l_return_status,
x_msg_count => l_msg_count,
x_msg_data => l_msg_data,
x_adjustment_id => l_adjustment_id,
x_adjustment_number => l_adjustment_number);
The warnings and the error messages put on the message stack by the API are retrieved after execution of this API by the calling program, as described in Example.
Result:
Non-revenue sales credits were added to salesperson 299 on this transaction by specifying only seven input parameters in the call to this API.
Call this routine to accept post-billing customer acceptance clauses in Receivables, and, if required, in Order Management, to remove these type of contingencies and to recognize revenue. This API routine has 5 input and 5 output parameters in total and is similar to the Unearn_Revenue routine described in AR_RevenueAdjust_PUB.Unearn_Revenue.
The following is the breakdown of the parameters:
Standard API parameters: 3
Revenue Adjustment parameters: 1 (revenue adjustment record type)
Organization Identifier parameter: 1
Standard API parameters: 3
Revenue Adjustment parameters: 2
For a description of this routine's standard parameters, see AR_RevenueAdjust_PUB.Unearn_Revenue.
The Rev_Adj_Rec_Type elements that are relevant to Record_Customer_Acceptance are exactly the same as already listed in AR_RevenueAdjust_PUB.Unearn_Revenue, with the following exceptions listed in this table:
| Parameter | Data-type | Required | Description |
|---|---|---|---|
| p_org_id | jtf_rs_salesreps.org_i d%type | Yes | Organization Identifier |
Call this routine to update the expiration date and period for specific time-based contingencies. This API routine has 5 input and 5 output parameters in total and is almost exactly the same as the Unearn_Revenue routine described in AR_RevenueAdjust_PUB.Unearn_Revenue.
The following is the breakdown of the parameters:
Standard API parameters: 3
Revenue Adjustment parameters: 1 (revenue adjustment record type)
Organization Identifier parameter: 1
Standard API parameters: 3
Revenue Adjustment parameters: 2
For a description of this routine's standard parameters, see AR_RevenueAdjust_PUB.Unearn_Revenue.
The Rev_Adj_Rec_Type elements that are relevant to Update_Contingency_Expirations are exactly the same as already listed in AR_RevenueAdjust_PUB.Unearn_Revenue, with the following exceptions listed in this table:
| Parameter | Data-type | Required | Description |
|---|---|---|---|
| p_org_id | jtf_rs_salesreps.org_i d%type | Yes | Organization Identifier. |
| p_customer_trx_id | ra_customer_trx.customer_trx_id | Yes | Identifies the affected invoices; affects all contingencies for the transaction. |
| p_customer_trx_line_id | ra_customer_trx_lines.customer_trx_line_id | Identifies the specific affected line and contingencies. | |
| p_contingency_id | ar_line_conts.contngency_id | Restricts updates to a specific type of contingency for the previously identified transaction or line. | |
| p_expiration_date | ar_line_conts.expiration_date | The new or resulting expiration date for the contingencies. | |
| p_expiration_days | ar_line_conts.expiration_days | The new offset for calculating the expiration date on the contingencies. The new expiration date is calculated as follows: Expiration Date = Expiration Event Date + Expiration Days |
Objective:
To update the expiration dates for all contingencies associated with a transaction to 31-DEC-2008, using a call to AR_Revenueadjust_PUB.Update_Contingency_Expirations and passing a minimum number of input parameters.
This table lists the input parameters:
| Parameter | Entered Value | Default Value |
|---|---|---|
| p_api_version | 2.0 | |
| p_init_msg_list | FND_API.G_TRUE | |
| p_commit | FND_API.G_TRUE | |
| p_org_id | 204 | |
| p_customer_trx_id | 1112234 | |
| p_customer_trx_line_id | NULL | |
| p_contingency_id | NULL | |
| p_expiration_date | 31-DEC-2008 | |
| p_expiration_days | NULL |
Important: For updating contingency expirations, you must enter a value for either the p_expiration_date or the p_expiration_days parameter. Not providing a value for either of the parameters raises a validation error. If you provide both the values, the API honors the p_expiration_date first.
The API call in this case would be:
AR_RevenueAdjust_PUB.update_contingency_expirations(
p_api_version => 2.0,
p_init_msg_list => FND_API.G_TRUE,
p_commit => FND_API.G_TRUE,
p_org_id => 204,
p_customer_trx_id => 1112234
p_expiration_date => '31-DEC-2008'
x_return_status => l_return_status,
x_msg_count => l_msg_count,
x_msg_data => l_msg_data);
The warnings and the error messages put on the message stack by the API are retrieved after execution of this API by the calling program, as described in Example.
Result:
All existing contingencies associated with this transaction now have their expiration dates set to 31-DEC-2008. On the expiration date, provided no other activity has already released the revenue, these contingencies will expire and revenue will be earned.
Messages play an important role in the effectiveness of API calls. The right message is raised at the right point to convey the exact error that has occurred or any warnings that have been raised. In the Revenue Adjustment API, all error messages and warnings raised during execution are put on the message stack and can be retrieved by the user as described in Exception Handling and Result Messages.
The following table lists all the error messages raised by the Revenue Adjustment API:
TYPE
E: Error message
W: Warning message
| MESSAGE CODE | MESSAGE TEXT | DESCRIPTION | TYPE |
|---|---|---|---|
| AR_INCOMPATIBLE_CREDIT_TYPE | The option of transferring "both" sales credit types is not available in conjunction with sales group transfers. | E | |
| AR_INVALID_SALESGROUP_ID | Please provide a valid sales group ID for sales credit transfers or additions. | E | |
| AR_RA_AMT_EXCEEDS_AVAIL_REV | The amount entered is greater than &TOT_AVAIL_REV, the total available revenue on the lines selected | This message is generated by the revenue adjustment API when there is insufficient adjustable revenue on the selected transaction lines to meet the specified amount. | E |
| AR_RA_BR_DISALLOWED | Revenue cannot be adjusted on bills receivable | E | |
| AR_RA_CATEGORY_NOT_ON_TRX | There are no lines with items for category ID &CATEGORY_ID on this transaction. | E | |
| AR_RA_CB_DISALLOWED | Revenue cannot be adjusted on chargebacks | E | |
| AR_RA_DEP_DISALLOWED | Revenue cannot be adjusted on deposits. | E | |
| AR_RA_DM_DISALLOWED | Revenue cannot be adjusted on debit memos or debit memo reversals | E | |
| AR_RA_FULL_CREDIT | One or more credit memos have been applied for the full amount of this invoice | E | |
| AR_RA_GL_DATE_CHANGED | GL date, &GL_DATE, is not in an open or future-enterable period. GL date has been changed to &NEW_GL_DATE | W | |
| AR_RA_GUAR_DISALLOWED | Revenue cannot be adjusted on guarantees. | E | |
| AR_RA_INVALID_AMOUNT_MODE | Amount mode &AMOUNT_MODE is invalid. | E | |
| AR_RA_INVALID_CAT_SEGMENTS | This combination of category segments is invalid: &CONCAT_SEGS. | E | |
| AR_RA_INVALID_CATEGORY | A valid category to which items belong that are currently on one or more lines on this transaction must be entered | E | |
| AR_RA_INVALID_CATEGORY_ID | Category ID &CATEGORY_ID is invalid. | E | |
| AR_RA_INVALID_CODE_COMB | An error occurred while generating the following accounting flexfield code combination: &CODE_COMBINATION | This message is generated by the revenue adjustment API because of an error with the specified accounting flexfield code combination. Possible causes: segment values could not be found by AutoAccounting or have been disabled. | E |
| AR_RA_INVALID_ITEM | A valid item that is currently on one or more lines on this transaction must be entered | E | |
| AR_RA_INVALID_ITEM_ID | Inventory item ID &ITEM_ID is invalid. | E | |
| AR_RA_INVALID_ITEM_SEGMENTS | This combination of item segments is invalid: &CONCAT_SEGS. | E | |
| AR_RA_INVALID_LINE_ID | Transaction line ID &CUST_TRX_LINE_ID is invalid. | E | |
| AR_RA_INVALID_LINE_MODE | Line selection mode &LINE_MODE is invalid. | E | |
| AR_RA_INVALID_REASON | Reason code &REASON_CODE is not a valid lookup code. | E | |
| AR_RA_INVALID_SALESCRED_TYPE | Sales credit type &SALESCRED_TYPE is invalid. | E | |
| AR_RA_INVALID_SALESREP_NUMBER | Salesperson number &SALESREP_NUMBER is invalid. | E | |
| AR_RA_ITEM_NOT_ON_TRX | There are no lines with item &ITEM_ID on this transaction. | E | |
| AR_RA_LINE_NOT_ON_TRX | There are no lines with line number &LINE_NUMBER on this transaction. | E | |
| AR_RA_NO_EARNED_REVENUE | There is no earned revenue on this transaction | This message is generated by the revenue adjustment API when there is no earned revenue on the selected transaction lines. | E |
| AR_RA_NO_FROM_CATEGORY | Please provide a from-category. | E | |
| AR_RA_NO_FROM_ITEM | Please provide a from-item. | E | |
| AR_RA_NO_FROM_LINE | Please provide a from-line. | E | |
| AR_RA_NO_OPEN_PERIODS | The transaction date must fall during an open period or prior to a future period | This message is generated by the revenue adjustment API because there are no open or future periods relating to the transaction date or following the transaction date. Revenue cannot be posted to periods prior to the transaction date. | E |
| AR_RA_NO_REV_SALES_CREDIT | Line &LINE_NUMBER has no revenue sales credits | This message is generated by the revenue adjustment API when a transaction line with no sales credits is encountered. | E |
| AR_RA_NO_REV_TO_ADJUST | There is no adjustable revenue on the selected lines | This message is generated by the revenue adjustment API when there is no adjustable revenue on the selected transaction lines. | E |
| AR_RA_NO_SELECTED_SALESCRED | There are no sales credits for this line selection available to transfer | E | |
| AR_RA_NO_TO_SALESREP | Please provide a valid salesperson number or ID for sales credit transfers or additions. | E | |
| AR_RA_NO_TRX_NUMBER | Please provide a valid transaction number or ID. | E | |
| AR_RA_NO_UNEARNED_REVENUE | There is no unearned revenue on this transaction | This message is generated by the revenue adjustment API when there is no unearned revenue on the selected transaction lines. | E |
| AR_RA_PARTIAL_CREDIT | One or more partial credit memos have been applied against this invoice | W | |
| AR_RA_PCT_EXCEEDS_AVAIL_PCT | The percentage entered is greater than &TOT_AVAIL_PCT, the total available percentage of adjustable revenue on the lines selected | This message is generated by the revenue adjustment API when there is insufficient adjustable revenue on the selected transaction lines to meet the specified percentage. | E |
| AR_RA_SALES_CREDIT_LIMIT | Revenue and non-revenue sales credits exceed &SALES_CREDIT_LIMIT percent for salesperson &SALESREP_NAME on line &LINE_NUMBER | This message is generated by the revenue adjustment API when the total percentage of revenue and non-revenue sales credits per salesperson per line exceeds the limit specified in system options. | E |
| AR_RA_SALESREP_NOT_ON_TRX | Salesperson &SALESREP_NAME does not have any sales credits on this transaction. | E | |
| AR_RA_TRX_NOTFOUND | Transaction number &TRX_NUMBER cannot be found. | E | |
| AR_RA_TRX_TOO_MANY_ROWS | There is more than one transaction with the transaction number &TRX_NUMBER. Please also provide a batch source to ensure uniqueness of the transaction. | E | |
| AR_RA_ZERO_AMOUNT | Amount entered cannot be zero | This message is generated by the revenue accounting API when attempting to adjust an amount of zero. | E |
| AR_RAPI_DESC_FLEX_INVALID | The entered values for the descriptive flexfield &DFF_NAME is invalid. | E | |
| AR_TW_INCORRECT_SALESCREDIT | Revenue sales credit not equal to line amount or 100% for line &LINE_NUMBER. | E | |
| AR_TAPI_TRANS_NOT_EXIST | Transaction does not exist. (CUSTOMER_TRX_ID: &CUSTOMER_TRX_ID). | E | |
| AR_TAPI_INVALID_SALESREP_ID | Invalid salesrep id. (SALESREP_ID: &SALESREP_ID) | E |