This document outlines in detail the Credit Memo Application API. This public API currently allows the application of an on-account credit memo to an activity such as Electronic Refund, which creates a customer refund for the credit memo via the creation of a negative miscellaneous receipt.
Please refer to the Oracle Receivables User Guide for more detail on customer credit refund functionality.
The Credit Memo Application API enables the following business actions:
Application of an on-account memo to the Electronic Refund activity, resulting in subsequent refund of the credit memo to the customer.
To apply or unapply an on-account credit memo to an activity, call the following APIs:
ar_cm_application_pub.activity_application: Applies an on-account credit memo to an activity.
ar_cm_application_pub.activity_unapplication: Unapplies an on-account credit memo from an activity.
Use this routine to apply an on-account credit memo to an activity, such as Electronic Refund. The API returns the receivable_application_id of the receivable_application created.
Standard API parameters: 4
Activity application parameters: 12 (including 1 descriptive flexfield parameter and 1 global descriptive flexfield parameter)
Standard API parameters: 3
Activity application parameters: 4 required parameters (might vary depending on the adjustment type)
The input descriptive flexfield parameter is a record of type attribute_rec_type:
TYPE attribute_rec_type IS RECORD
(p_attribute_category IN VARCHAR2,
p_attribute1 IN VARCHAR2,
p_attribute2 IN VARCHAR2,
p_attribute3 IN VARCHAR2,
p_attribute4 IN VARCHAR2,
p_attribute5 IN VARCHAR2,
p_attribute6 IN VARCHAR2,
p_attribute7 IN VARCHAR2,
p_attribute8 IN VARCHAR2,
p_attribute9 IN VARCHAR2,
p_attribute10 IN VARCHAR2,
p_attribute11 IN VARCHAR2,
p_attribute12 IN VARCHAR2,
p_attribute13 IN VARCHAR2,
p_attribute14 IN VARCHAR2,
p_attribute15 IN VARCHAR2);
The input global descriptive flexfield parameter is a record of type global_ attribute_rec_type:
TYPE global_attribute_rec_type IS RECORD
(p_global_attribute_category IN VARCHAR2,
p_global_attribute1 IN VARCHAR2,
p_global_attribute2 IN VARCHAR2,
p_global_attribute3 IN VARCHAR2,
p_global_attribute4 IN VARCHAR2,
p_global_attribute5 IN VARCHAR2,
p_global_attribute6 IN VARCHAR2,
p_global_attribute7 IN VARCHAR2,
p_global_attribute8 IN VARCHAR2,
p_global_attribute9 IN VARCHAR2,
p_global_attribute10 IN VARCHAR2,
p_global_attribute11 IN VARCHAR2,
p_global_attribute12 IN VARCHAR2,
p_global_attribute13 IN VARCHAR2,
p_global_attribute14 IN VARCHAR2,
p_global_attribute15 IN VARCHAR2,
p_global_attribute16 IN VARCHAR2,
p_global_attribute17 IN VARCHAR2,
p_global_attribute18 IN VARCHAR2,
p_global_attribute19 IN VARCHAR2,
p_global_attribute20 IN VARCHAR2);
The following table lists the standard API parameters which are common to all the routines in the credit memo application 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 in-compatibility 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_validation_level | IN | NUMBER | FND_API.G_VALID_LEVEL_FULL | Not to be used currently as this is a public API . | |
| x_return_status | OUT | VARCHAR2 | Represents the API overall return status. See: Exception Handling and Result Messages. | ||
| 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 |
The following table lists the parameters that are relevant to the activity_application routine:
| Parameter | Type | Data-type | Required* | Description |
|---|---|---|---|---|
| p_customer_trx_id | IN | NUMBER | Yes | Customer transaction identifier of the on account credit memo to be applied. Default: None Validation: Must be a completed on-account credit memo (not a regular credit memo related to an invoice where previous_customer_trx_id has a value). Must have a receipt method. Receipt method must belong to a receipt class that allows remittance. Receipt method must have a remittance bank account. Must have customer bank account details. Must have a negative original amount due. Must not be negative due to overpayment. Errors: AR_REF_NO_PAYMENT_METHOD, AR_REF_NO_CUST_BANK, AR_REF_NOT_OACM, AR_REF_CM_INCOMPLETE, AR_REF_CM_POSITIVE, AR_REF_MORE_THAN_CM_AMT, AR_REF_RCT_CLASS_REMIT, AR_REF_NO_REMIT_BANK |
| p_amount_applied | IN | NUMBER | Yes | The amount of the credit memo to apply to an activity. Default: None Validation: Must be greater than zero. Must not cause the credit memo to be overapplied. Total applied to Electronic Refund, including this application and other applications on the same credit memo, must not fall outside the approval limits or Credit Memo refunds specified for the user/currency. Errors: AR_CKAP_OVERAPP, AR_REF_CM_APP_NEG, AR_REF_USR_LMT_OUT_OF_RANGE |
| p_applied_payment_schedule_id | IN | NUMBER | Yes | The payment_schedule_id of the activity being applied to. Default: None Validation: Only 1 value is currently allowed: -8 (Electronic Refund) Error:AR_RAPI_APP_PS_ID_INVALID |
| p_receivable_trx_id | IN | NUMBER | Yes | Receivables Transaction Identifier of the activity being applied to. Default: None Validation: Must be of type Credit Memo Refund. Error: AR_RAPI_ACTIVITY_X_INVALID |
| p_apply_date | IN | DATE | No | The date the credit memo is applied to the activity. Default: The greater of system date and transaction date. Validation: Must not precede the transaction date of the credit memo. Error: AR_APPLY_BEFORE_TRANSACTION |
| p_apply_gl_date | IN | DATE | No | Date that this application will be posted to the General Ledger. Default: Gets defaulted to the system date if it is in an open or future enterable period, otherwise:
Validation: It is valid if the following conditions are true:
Error: AR_INVALID_APP_GL_DATE, AR_VAL_GL_INV_GL |
| p_ussgl_transaction_code | IN | VARCHAR2(30) | No | Code defined by public sector accounting. Default: None Validation: None Error: None |
| p_called_from | IN | VARCHAR2(20) | No | This parameter is used to identify the calling routine. Default: Null Validation: None Error: None |
| p_attribute_record | IN | attribute_rec_type | No | This is a record type which contains all 15 descriptive flexfield segments and one descriptive flexfield structure defining column. It represents the Receivable Application Information flexfield. Default: DFF APIs used to do the defaulting Validation: DFF APIs used to do the validation depending on setup Error: AR_RAPI_DESC_FLEX_INVALID |
| p_global_attribute_record | IN | global_attribute_rec_type | No | This is a record type which contains all 20 global descriptive flexfield segments and one global descriptive flexfield structure defining column. Default: None Validation: None |
| p_comments | IN | VARCHAR2(240) | No | User's comments |
| p_chk_approval_limit_flag | IN | VARCHAR2(1) | No | Flag used to optionally override user approval limits for Credit Memo refunds. Values: 'Y' = Yes (check limits), 'N' = No (do not check limits) Default: 'Y' Validation: None |
| p_application_ref_type | IN OUT | VARCHAR2(30) | No | The context of application ref number/id is passed back in this parameter. For Electronic refunds this will be MISC_RECEIPT Default: None Validation: None Error: None |
| P_application_ref_id | IN OUT | NUMBER | No | For Electronic Refunds, the cash_receipt_id of the negative miscellaneous receipt created for the refund is passed back in this parameter. Default: None Validation: None Error: None |
| p_application_ref_num | IN OUT | VARCHAR2(30) | No | For Electronic Refunds, the receipt number for the resulting miscellaneous receipt will be passed back in this parameter. Default: None Validation: None Error: None |
| p_receivable_application_id | OUT | NUMBER(15) | No | The receivable application identifier of the activity application. |
*If the values for the Required parameters are not passed in a call to this API, then the call itself will fail. However, depending on the business scenario, you must pass in values for other parameters to successfully create the business object. Otherwise, error messages will be reported.
This section explains the validation in this API, which does not relate directly to any of the above columns.
Only checked if p_chk_approval_limits_flag <> 'N'.
Limits must exist for the user calling the credit memo application API for the credit memo currency.
The total amount applied to Electronic Refund for a particular credit memo must fall within the limits.
Objective: To apply an on-account credit memo to the Electronic Refund activity using a call to ar_cm_application_pub.activity_application and passing the minimum number of input parameters.
This table lists the entered parameters:
| Parameter | Entered Value | Default Value |
|---|---|---|
| p_api_version | 1.0 | |
| p_init_msg_list | FND_API.G_TRUE | |
| p_customer_trx_id | 1001 | |
| p_amount_applied | 100 | |
| p_applied_payment_schedule_id | 1071 | |
| p_receivables_trx_id | 1089 |
This table lists the defaulted input parameters, which were not entered:
| Parameter | Entered Value | Default Value |
|---|---|---|
| p_apply_date | sysdate | |
| p_apply_gl_date | sysdate | |
| p_chk_approval_limit_flag | 'Y' |
The API call in this case would be:
Ar_cm_application_pub.activity_application(
p_api_version => 1.0,
p_init_msg_list => FND_API.G_TRUE,
p_customer_trx_id => 1001,
p_amount_applied => 100,
p_applied_payment_schedule_id => 1071,
p_receivables_trx_id => 1089,
x_return_status => l_return_status,
x_msg_count => l_msg_count,
x_msg_data => l_msg_data,
p_application_ref_type => l_application_ref_type,
p_application_ref_id => l_application_ref_id,
p_application_ref_num => l_application_ref_num);
The warnings and error messages put on the message stack by the API are retrieved after 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: An electronic refund can be created for an on account credit memo by specifying only 6 input parameters in the above API call.
Call this routine to reverse an activity application on an on-account credit memo. Such applications currently include only Electronic Refunds.
Standard API parameters: 4
Activity unapplication parameters: 4
Standard API parameters: 3
Activity unapplication parameters: 0
For descriptions of the seven standard API parameters, see ar_cm_application_pub.activity_application.
The following table lists the parameters that are relevant to the activity_unapplication routine:
| Parameter | Type | Data-type | Required* | Description |
|---|---|---|---|---|
| p_customer_trx_id | IN | NUMBER(15) | No | The customer transaction identifier of the on-account credit memo from which the activity application is to be unapplied. Default: Null Validation:
Error: AR_RAPI_CUST_TRX_ID_INVALID AR_RAPI_MULTIPLE_ACTIVITY_APP |
| p_receivable_application_id | IN | NUMBER(15) | No | Identifies the receivable application. Used to derive the customer trx id if not specified. Default: If only one Electronic Refund application exists, then receivable-application_id is taken from it. Validation:
Error: AR_RAPI_REC_APP_ID_INVALID |
| p_reversal_gl_date | IN | DATE | The reversal gl date used for the accounting entries. Default: Gets defaulted to the application gl date if it is a valid gl_date, otherwise:
Validation:
Error: AR_INVALID_APP_GL_DATE, AR_RW_BEFORE_APP_GL_DATE, AR_VAL_GL_INV_GL |
|
| p_called_from | IN | VARCHAR2(20) | Yes | Used to indicate which program is calling this API. Default: None Validation: None Error: None |
Objective: To unapply an activity application using a call to ar_cm_application_pub.activity_unapplication, and passing a minimum number of input parameters.
This table lists the entered parameters:
| Parameter | Entered Value | Default Value |
|---|---|---|
| p_api_version | 1.0 | |
| p_receivable_application_id | 10051 |
This table lists the defaulted input parameters, which were not entered:
| Parameter | Entered Value | Default Value |
|---|---|---|
| p_customer_trx_id | 20338 | |
| p_reversal_gl_date | 01-JUN-2000 | |
| p_called_from |
The retrieval and handling of the warnings and error messages, put on the message stack by the API during execution, are the same as described in Exception Handling and Result Messages.
The following table lists all the error messages raised by the Credit Memo Application API:
TYPE
E: Error message
W: Warning message
| MESSAGE_CODE | MESSAGE_TEXT | EXPLANATION | TYPE |
|---|---|---|---|
| AR_APPLY_BEFORE_TRANSACTION | Apply Date must be greater than or equal to the Transaction Date. | E | |
| AR_CKAP_OVERAPP | You cannot over apply this transaction. | This message will appear if the amount being applied to the credit memo results in a change of sign of the balance due remaining | E |
| AR_INVALID_APP_GL_DATE | GL date, &GL_DATE, is not in an open or future-enterable period. | Either the GL date must be changed, or the period in which it falls must be opened or made future-enterable. | E |
| AR_RAPI_ACTIVITY_INVALID | The receivables activity name is invalid. | E | |
| AR_RAPI_ACTIVITY_X_INVALID | The specified combination of payment schedule identifier and receivables transaction identifier is invalid. | The activity type derived from the receivables_trx_id does not match with the activity type of the specified payment_schedule_id. | E |
| AR_RAPI_APP_PS_ID_INVALID | Applied payment schedule identifier has an invalid value. | E | |
| AR_RAPI_APP_PS_RA_ID_X_INVALID | Invalid receivable application identifier for the specified applied payment schedule identifier. | E | |
| AR_RAPI_APPLIED_AMT_NULL | Applied amount could not be defaulted. | The p_applied_amount was not specified by the user and it could not be defaulted from the specified transaction | E |
| AR_RAPI_CUST_TRX_ID_INVALID | Invalid customer transaction identifier. | E | |
| AR_RAPI_CUST_TRX_ID_NULL | Customer transaction identifier is null. | E | |
| AR_RAPI_DESC_FLEX_INVALID | The entered values for the descriptive flexfield &DFF_NAME is invalid. | E | |
| AR_RAPI_RCT_MD_ID_INVALID | Invalid receipt method identifier. | E | |
| AR_RAPI_REC_APP_ID_INVALID | Invalid receivable application identifier. | E | |
| AR_RAPI_REC_APP_ID_NULL | Receivable application identifier is null. | E | |
| AR_RAPI_REC_TRX_ID_INVALID | Invalid receivable transaction identifier. | E | |
| AR_RAPI_REC_TRX_ID_NULL | Please enter a receivables transaction identifier. | E | |
| AR_RAPI_REV_GL_DATE_NULL | Reversal GL date is null. | E | |
| AR_RAPI_TRX_PS_ID_X_INVALID | Invalid applied payment schedule identifier for the specified transaction. | The p_applied_payment_schedule_id specified by the user does not match with the payment_schedule_id derived from the p_customer_trx_id and the p_installment. | E |
| AR_RAPI_TRX_PS_NOT_DEF_CUS | The customer could not be defaulted from the entered transaction and the applied payment schedule identifier. | E | |
| AR_RAPI_TRX_RA_ID_X_INVALID | The activity type for the entered receivable transaction identifier does not match with the activity of the entered payment schedule identifier . | E | |
| AR_REF_BEFORE_CM_GL_DATE | The GL date cannot be before the credit memo GL date. | E | |
| AR_REF_CM_APP_NEG | Only positive credit memo refund amounts are allowed. | E | |
| AR_REF_CM_INCOMPLETE | Please complete this credit memo. | E | |
| AR_REF_CM_POSITIVE | Credit memo refunds are only allowed on negative credit memos. | E | |
| AR_REF_MORE_THAN_CM_AMT | You cannot refund more than the credit memo amount. | E | |
| AR_REF_NO_CUST_BANK | To enable credit memo refunds, please add customer bank details to the credit memo. | E | |
| AR_REF_NO_APPROVAL_LIMIT | Credit memo refund approval limits do not exist for this user and currency. | E | |
| AR_REF_NO_PAYMENT_METHOD | To enable credit memo refunds, please add a receipt method to the credit memo. | E | |
| AR_REF_NO_REMIT_BANK | To enable credit memo refunds, the credit memo receipt method must belong to a receipt class with an assigned remittance bank. | E | |
| AR_REF_NOT_OACM | Credit memo refunds are only allowed for on-account credit memos. | Only transactions with Credit Memo class and unattached to another transaction are allowed. | E |
| AR_REF_RCT_CLASS_REMIT | To enable credit memo refunds, the receipt class associated with this credit memo receipt method must require remittance. | E | |
| AR_REF_USR_LMT_OUT_OF_RANGE | The total refund amount must be within &FROM_AMOUNT and &TO_AMOUNT. | E | |
| AR_RW_BEFORE_APP_GL_DATE | Reversal GL Date must be on or after original GL Date of &GL_DATE. | E | |
| AR_VAL_GL_INV_GL | The GL date should not be prior to the invoice's GL date. | E |