Skip Headers

Oracle Receivables Reference Guide
Release 12.1
Part Number E13512-04
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

Revenue Adjustment API User Notes

Overview

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:

Basic Business Needs

The Revenue Adjustment API addresses the following basic functionality via different API calls:

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.

API Usage

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:

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.

AR_RevenueAdjust_PUB.Unearn_Revenue

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:

Input

Standard API parameters: 3

Revenue Adjustment parameters: 1 (revenue adjustment record type)

Output

Standard API parameters: 3

Revenue Adjustment parameters: 2

Parameter Descriptions

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:
  • T - total adjustable revenue

  • A - amount

  • P - percent


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:
  • A - All transaction lines

  • C - Specific category

  • I - Specific item

  • S - Specific line.


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:
  • The date is in an Open or Future period, or it is in a Never Opened period and the Allow Not Open Flag is set to Yes.

  • The date is greater than or equal to the trx_date

  • The period cannot be an Adjustment period.


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:
  • If the most recent open period is prior to the current date: last date of that period

  • If there is a period open after the current date: first date of the last open period


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

Example

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.

AR_RevenueAdjust_PUB.Earn_Revenue

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:

Input

Standard API parameters: 3

Revenue Adjustment parameters: 1 (revenue adjustment record type)

Output

Standard API parameters: 3

Revenue Adjustment parameters: 2

Parameter Descriptions

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.

Example

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.

AR_RevenueAdjust_PUB.Transfer_Sales_Credits

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:

Input

Standard API parameters: 3

Revenue Adjustment parameters: 1 (revenue adjustment record type)

Output

Standard API parameters: 3

Revenue Adjustment parameters: 2

Parameter Descriptions

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:
  • the earliest of the transaction date and any parent commitment/invoice dates, and

  • the latest of the current date, transaction date, and any parent commitment/invoice dates.


Error: AR_INVALID_SALESGROUP_ID
sales_credit_type VARCHAR2(15) Yes The type of sales credit being transferred. Possible values:
  • R = revenue sales credits

  • N = non-revenue sales credits

  • B = both


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

Example

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.

AR_RevenueAdjust_PUB.Add_Non_Revenue_Sales_Credits

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:

Input

Standard API parameters: 3

Revenue Adjustment parameters: 1 (revenue adjustment record type)

Output

Standard API parameters: 3

Revenue Adjustment parameters: 2

Parameter Descriptions

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:
  • the earliest of the transaction date and any parent commitment/invoice dates, and

  • the latest of the current date, transaction date, and any parent commitment/invoice dates.


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:
  • A - amount

  • P - percent


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

Example

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.

AR_Revenueadjust_PUB.Record_Customer_Acceptance

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:

Input

Standard API parameters: 3

Revenue Adjustment parameters: 1 (revenue adjustment record type)

Organization Identifier parameter: 1

Output

Standard API parameters: 3

Revenue Adjustment parameters: 2

Parameter Descriptions

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

AR_Revenueadjust_PUB.Update_Contingency_Expirations

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:

Input

Standard API parameters: 3

Revenue Adjustment parameters: 1 (revenue adjustment record type)

Organization Identifier parameter: 1

Output

Standard API parameters: 3

Revenue Adjustment parameters: 2

Parameter Descriptions

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

Example

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

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.

WARNINGS AND ERRORS

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