This document outlines the use of the Credit Memo Approval and Creation API. This API lets you achieve the following task using simple calls to PL/SQL functions:
Initiate a Credit Memo Request workflow process request for the creation of a credit memo against a specified transaction either with or without an approval process
Check the status of an existing Credit Memo Request workflow process request
Apply on-account credit memos to a debit item
Unapply on-account credit memos to a debit item
To create a credit memo using an existing, user-defined Credit Memo Request workflow approval process, set the p_skip_workflow_flag parameter to N. In this case, the workflow process proceeds independently of the Credit Memo Approval and Creation API. If the disputed amount of the invoice is approved, then a credit memo is automatically created.
Note: You must set up the Credit Memo Request workflow before using the Credit Memo Approval and Creation API. For more information, see the Oracle Receivables User Guide.
To create a credit memo directly, without sending a request through the workflow approval process, set the p_skip_workflow_flag parameter to Y. If you set the p_skip_workflow_flag parameter to Y, then the Credit Memo Approval and Creation API bypasses the workflow process and calls code to automatically create the credit memo.
When you set the p_skip_workflow_flag parameter to Y, you might also have to set values for its associated parameters: p_credit_method_installments, p_credit_method_rules, and p_batch_source_name. For more information, see the description of the AR_CREDIT_MEMO_API_PUB.Create_Request routine.
You cannot use the Credit Memo Approval and Creation API to generate on-account credit memos. You must specify an existing transaction to credit.
To initiate a Credit Memo Request workflow process request, to check the status of an existing Credit Memo Request workflow process request, and to apply and unapply on-account credit memos to a debit item, use the following routines:
AR_CREDIT_MEMO_API_PUB.Create_Request: Use this routine to initiate the Credit Memo Request workflow process by making a credit memo workflow request.
AR_CREDIT_MEMO_API_PUB.Get_Request_Status: Use this routine to view the status of an existing request
AR_CM_API_PUB.Apply_On_Account: Use this routine to apply on-account credit memos to a debit item.
AR_CM_API_PUB.Unapply_On_Account: Use this routine to unapply on-account credit memo applied to a debit item.
You must define three HTML pages that display this information:
The credit memo dispute request
The original transaction details
The transaction activities
You provide the API with the URLs of these pages. When workflow notifications are sent to the collector, approver, and receivable roles, links to the URLs are set in the message body of the notification. If the URLs are not correctly set up, then you will receive an error message such as "URL not found" when you click on the links.
You must also set up the Credit Memo Request workflow before you use the Credit Memo Approval and Creation API. For more information, see: Setting Up Credit Memo Request Workflow, Oracle Receivables User Guide.
You can call this routine to create the Credit Memo Request workflow process request. When the workflow request has been created, the API returns a unique request ID number (p_request_id) that you can use to track the status of the request. The following is a breakdown of this routine's parameters, based upon parameter type:
This table lists and describes the standard parameters common to all routines in the Credit Memo Approval and Creation API.
| Parameter | Type | Data-type | Required | Default Value | Description |
|---|---|---|---|---|---|
| p_api_version | IN | NUMBER | Yes | Used to compare version numbers of incoming calls to current version number. | |
| p_init_msg_list | IN | VARCHAR2 | FND_API.G_FALSE | Set to TRUE to have the API automatically initialize the message list. | |
| p_commit | IN | VARCHAR2 | FND_API.G_FALSE | Set to TRUE to have the API commit automatically. | |
| x_return_status | OUT | VARCHAR2 | Overall return status of the API. | ||
| x_msg_count | OUT | NUMBER | Number of messages in the API message list. | ||
| x_msg_data | OUT | VARCHAR2 | Message in encoded format if x_msg_count=1. |
This table lists and describes parameters that specifically pertain to the Create_Request routine:
See Legend for this table's legend.
| Parameter | Type | Data-type | Required | Description |
|---|---|---|---|---|
| p_customer_trx_id | IN | ra_customer_trx.customer_trx_id%type | Yes | Customer_trx_id of the disputed invoice. |
| p_line_credit_flag | IN | ra_cm_request.line_credit_flag%type | Yes | This value should be set to Y if the dispute is at the line level. |
| p_line_amount | IN | ra_cm_request.line_amount%type | Yes/No | Amount of the line dispute at the header level. If the dispute is at the header level, you should enter either the line_amount, tax_amount or freight_amount. |
| p_tax_amount | IN | ra_cm_request.tax_amount | Yes/No | Amount of the tax dispute at the header level. |
| p_freight_amount | IN | ra_cm_request.freight_amount | Yes/No | Amount of the freight dispute at header level. |
| p_cm_reason_code | IN | ra_cm_requests.cm_reason_code%type | YES | User defined lookup code that represents the reason for the invoice dispute. Should be a valid lookup_code for the lookup_type CREDIT_MEMO_REASON. |
| p_comments | IN | ra_cm_requests.comments%type | No | Comments about the credit memo request, entered if required. These comments appear in the notes region of the Transaction window. This also includes the internal comments posted by user and are not visible to customers. |
| p_orig_trx_number | IN | VARCHAR2 | No | Enter the duplicate invoice number if using the "Duplicate Billing" reason code. |
| p_tax_ex_cert_num | IN | VARCHAR2 | No | Tax exemption certificate number. |
| p_request_url* | IN | VARCHAR2 | No** | URL that displays the information of the actual credit memo dispute request.* See Legend for this table's legend. |
| p_transaction_url | IN | VARCHAR2 | No** | URL that displays the information of the original transaction. See Legend for this table's legend. |
| p_trans_act_url | IN | VARCHAR2 | No** | URL that displays information about the original transaction activities. See Legend for this table's legend. |
| p_cm_line_tbl(x).customer_trx_line_id | IN | cm_line_tbl_type_cover%type | Yes/No | This value must be entered only if the dispute is at the line level. This value indicates the line_id that is in dispute.
Note: Where p_cm_line_tbl(x), x indicates the index. The dispute can be for multiple lines. |
| p_skip_workflow_flag | IN | VARCHAR2 | No | Defaults to N. If this value is set to Y, the entire workflow is skipped for that particular request and the credit memo is directly created. |
| p_credit_method_installments | IN | VARCHAR2 | No | The p_credit_method_installments is the credit method that is used for crediting a transaction that uses split payment terms. Choices include PRORATE, LIFO, FIFO, or NULL. This value may be required if the p_skip_workflow_flag is set to Y.
|
| p_credit_method_rules | IN | VARCHAR2 | No | The p_credit_method_rules is the credit method for crediting a transaction which uses an accounting rule. Choices include PRORATE, LIFO, UNIT, or NULL. This value may be required if the p_skip_workflow_flag is set to Y.
|
| p_batch_source_name | IN | VARCHAR2 | No | This value is required if the p_skip_workflow_flag is set to Y. |
| p_org_id | IN | NUMBER | No | This value is required and it is used to identify the organization where the credit memo is sourced from. |
| x_request_id | OUT | VARCHAR2 | Yes | Request_id of the credit memo that is returned if the data passed is valid and the credit memo request is created. |
| p_attribute_rec | IN | arw_cmreq_cover.pq_attribute_rec_type | No | Default value is ATTRIBUTE_REC_CONST. |
| p_interface_attribute_rec | IN | arw_cmreq_cover.pq_interface_rec_type | No | Default value is ATTRIBUTE_REC_CONST |
| p_global_attribute_rec | IN | arw_cmreq_cover.pq_global_attribute_rec_type | No | Default value is GLOBAL_ATTRIBUTE_REC_CONST. |
| P_DISPUTE_DATE | IN | DATE | No | NULL |
* The request confirmation page might need the request_id as a parameter to query the information. This will not be available to the calling program when creating the p_request_url parameter because the request_id is the out parameter of the API. Calling programs should leave the request_id value blank and the table handler will add the request_id value and pass it to Workflow. The code searches for the "req_id=" string and replaces it with req_id="req_id". The parameter name must be req_id.
For example: For the old technology stack (PL/SQL), the following represents the request URL in iReceivables to call the "Request Confirmation" page. Note that no value has been entered for the req_id.
'arw_single_trx.single_cm_page?req_id='||'req_id='||'`&component='||glb_inv_part||'`&pct_change='||glb_percent_change;
** If the calling application does not enter the request, transaction, and transaction activities URLs, then you will see a default page reading "Unavailable" when you click on these links in the notifications screen. It is strongly recommended that the calling application have the UI (user interface) display these pages and pass these URLs to the API.
The API validates all parameters that you enter. If any of the required fields are missing or invalid, then the API returns an error message. A list of error messages is documented in Messages.
This example shows a simple test case for creating a credit memo request for a dispute at the header level:
Objective:
To create a credit memo request.
Parameters entered:
customer_trx_id = 99999
line_credit_flag = N
line_amount = -100
cm_reason_code = RETURN
Call to the API:
AR_CREDIT_MEMO_API_PUB.Create_Request(
x_return_status => p_return_status,
x_msg_count => p_msg_count,
x_msg_data => p_msg_data ,
CREDIT MEMO REQUEST PARAMETERS:
p_customer_trx_id => 99999,
p_line_credit_flag => 'N',
p_line_amount => -100,
p_cm_reason_code => 'RETURN',
p_request_url => 'arw_single_trx.single_trx_page?p1=19769&p2=1&wf=Y',
p_transaction_url => 'arw_single_trx.single_trx_page?p1=19769&p2=1&wf=Y'
p_trans_act_url => 'arw_single_trx.single_act_page?p1=19769&p2=1&wf=Y'
x_request_id => p_request_id
Use this routine to view the Credit Memo Request workflow process request status. The API returns the status of the request and information about where the request is in the workflow. The following is a breakdown of parameters for this routine, based on parameter type:
This table shows the standard API parameters common to all routines in the Credit Memo Approval and Creation 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. | |
| p_init_msg_list | IN | VARCHAR2 | FND_API.G_FALSE | Set to TRUE to have the API automatically initialize the message list. | |
| x_return_status | OUT | VARCHAR2 | Overall return status of the API. | ||
| x_msg_count | OUT | NUMBER | Number of messages in the API message list. | ||
| x_msg_data | OUT | VARCHAR2 | Message, in encoded format if x_msg_count=1. |
This table shows parameters that specifically pertain to the Get_Request_Status routine:
| Parameter | Type | Data-type | Required | Description |
|---|---|---|---|---|
| p_request_id | IN | ra_cm_requests.request_id%type | YES | ID of the credit memo request whose status you are checking. |
| x_status_meaning | OUT | VARCHAR2 | Status of the credit memo request. | |
| x_reason_meaning | OUT | VARCHAR2 | Reason for the dispute of the credit memo request. | |
| x_customer_trx_id | OUT | ra_customer_trx.customer_trx_id%type | Customer transaction ID for the dispute of the credit memo request. | |
| x_cm_customer_trx_id | OUT | ra_customer_trx.customer_trx_id%type | Credit memo transaction ID that was created for the dispute. | |
| x_line_amount | OUT | ra_cm_requests.line_amount%type | Total amount of dispute for lines. | |
| x_tax_amount | OUT | ra_cm_requests.tax_amount%type | Total amount of dispute for tax. | |
| x_freight_amount | OUT | ra_cm_requests.freight_amount%type | Total amount of dispute for freight. | |
| x_line_credits_flag | OUT | ra_cm_requests.line_credits_flag%type | Indicates whether the dispute is at the line level or the header level. If the value is set to Y, the dispute is at the line level. | |
| x_created_by | OUT | wf_users.display_name%type | Name of the requestor. | |
| x_creation_date | OUT | DATE | Date of the request. | |
| x_approval_date | OUT | DATE | Credit memo approval date if the credit memo has been created for the request. | |
| x_comments | OUT | ra_cm_requests.comments% type | Comments entered by the requestor. | |
| x_cm_line_tbl | OUT | cm_line_tbl_type_cover | Table that contains the line level dispute information. The values in the table will be set if the x_line_credits_flag = Y. | |
| x_cm_activity_tbl | OUT | cm_activity_tbl_type_cover | Table that contains the status of the activities for the request. | |
| x_cm_notes_tbl | OUT | cm_notes_tbl_type_cover | Table that contains the notes inserted for the transaction that is disputed. |
Note:
TYPE CM_LINE_REC_TYPE_COVER IS RECORD
customer_trx_line_id: ra_customer_trx_lines.customer_trx_line_id%type,
extended_amount: ra_customer_trx_lines.extended_amount%type,
quantity_credited: number,
price: number;
TYPE CM_LINE_TBL_TYPE_COVER
IS TABLE OF
CM_LINE_REC_TYPE_COVER
INDEX BY BINARY INTEGER;
x_cm_line_tbl CM_LINE_TBL_TYPE_COVER;
TYPE CM_ACTIVITY_REC_TYPE_COVER IS RECORD
begin_date: DATE,
activity_name: VARCHAR2(80),
status: wf_item_activity_statuses.activity_status%type,
user: wf_item_activity_statuses.activity_user%type);
TYPE CM_ACTIVITY_TBL_TYPE_COVER
IS TABLE OF
CM_ACTIVITY_REC_TYPE_COVER
INDEX BY BINARY INTEGER;
x_cm_activity_tbl CM_ACTIVITY_TBL_TYPE_COVER;
TYPE CM_NOTES_REC_TYPE_COVER IS RECORD
( NOTES ar_notes.text%type);
TYPE CM_NOTES_TBL_TYPE_COVER
IS TABLE OF
CM_NOTES_REC_TYPE_COVER
INDEX BY BINARY INTEGER;
x_cm_notes_tbl CM_NOTES_TBL_TYPE_COVER;
The API validates all parameters that you enter. If any of the required fields are missing or invalid, then the API returns an error message. A list of error messages is documented in Messages.
The following example is a simple test case for viewing the status of the credit memo request.
Objective:
To get the status of the credit memo request.
Parameters entered:
request_id = 122
Call to the API:
AR_CREDIT_MEMO_API_PUB.Get_Request_Status(
p_api_version => 1.0,
x_msg_count => msg_count ,
x_msg_data => msg_data,
x_return_status => return_status,
p_request_id => request_id,
x_status_meaning => status_meaning,
x_reason_meaning => reason_meaning,
x_customer_trx_id => customer_trx_id,
x_cm_customer_trx_id => cm_customer_trx_id,
x_line_amount => line_amount,
x_tax_amount => tax_amount,
x_freight_amount => freight_amount,
x_line_credits_flag => line_credits_flag,
x_created_by => created_by,
x_creation_date => creation_date,
x_cm_line_tbl => cm_line_tbl,
x_cm_activity_tbl => cm_activity_tbl,
x_cm_notes_tbl => cm_notes_tbl);
Use this routine to apply on-account credit memos to a debit item.
Use this routine to unapply on-account credit memo applied to a debit item.
The following table describes the possible messages returned by the Credit Memo Approval and Creation API.
| Message Number | Message Name | Message Description |
|---|---|---|
| 11936 | AR_RAXTRX-1719 | You must supply a reason code for your credit memo transaction. |
| 11091 | AR_CKAP_OVERAPP | You cannot overapply this transaction. |
| 42711 | AR_TAPI_LINE_NOT_EXIST | Line does not exist (customer_trx_line_id:[customer_trx_line_id]). |
| 42756 | AR_TAPI_TRANS_NOT_EXIST | Transaction does not exist (customer_trx_id:[customer_trx_id]). |
| 294003 | AR_CMWF_API_INVALID_VALUE | You specified an invalid value for the LINE_CREDIT_FLAG parameter. The valid values are Y and N. |
| 294004 | AR_CMWF_API_NO_LINES_INFO | The value for LINES_CREDIT_FLAG is Y, please provide at least one line level information. |
| 294002 | AR_CMWF_API_INVALID_REQUEST_ID | Request does not exist (REQUEST_ID: &REQUEST_ID) |