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

Credit Memo Approval and Creation API User Notes

Overview

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:

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.

API Usage

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:

Prerequisites

You must define three HTML pages that display this information:

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.

AR_CREDIT_MEMO_API_PUB.Create_Request

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:

Standard Parameters

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.

Create_Request Parameters

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 Leend 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.

  • This parameter is mandatory if the credit memo is against a transaction that uses split payment terms and LINE_TYPE = LINE or CHARGES, or you are passing header freight.

  • Do not enter a value for this parameter if LINE_TYPE = TAX, or if you are passing freight for a specific line.

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.

  • This parameter is mandatory if the credit memo is against a transaction which uses an accounting rule and LINE_TYPE = LINE or CHARGES, or you are passing header freight.

  • Do not enter a value for this parameter if LINE_TYPE = TAX, or if you are passing freight for a specific line.

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

Legend

* 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.

Parameter validation

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.

Example

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

AR_CREDIT_MEMO_API_PUB.Get_Request_Status

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:

Standard parameters

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.

Get_Request_Status parameters

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;

Parameter validation

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.

Example

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); 

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.

Messages

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)