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 Application API User Notes

Overview

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.

Basic Business Needs

The Credit Memo Application API enables the following business actions:

API Usage

To apply or unapply an on-account credit memo to an activity, call the following APIs:

ar_cm_application_pub.activity_application

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.

Input Parameters

Standard API parameters: 4

Activity application parameters: 12 (including 1 descriptive flexfield parameter and 1 global descriptive flexfield parameter)

Output Parameters

Standard API parameters: 3

Activity application parameters: 4 required parameters (might vary depending on the adjustment type)

Parameter Descriptions

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

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


Validation:
It is valid if the following conditions are true:
  • The date is in an Open or Future period

  • The period cannot be an Adjustment period

  • Must not precede the credit memo GL date


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 num/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.

Validation

This section explains the validation in this API, which does not relate directly to any of the above columns.

User Approval Limits

Only checked if p_chk_approval_limits_flag <> ‘N’.

Example

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.

ar_cm_application_pub.activity_unapplication

Call this routine to reverse an activity application on an on-account credit memo. Such applications currently include only Electronic Refunds.

Input Parameters

Standard API parameters: 4

Activity unapplication parameters: 4

Output Parameters

Standard API parameters: 3

Activity unapplication parameters: 0

Parameter Descriptions

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:
  1. Must have at least one Electronic Refund application

  2. Must have only 1 Electroinic Refund application if receivable_application_id is not supplied

  3. Must be specified if receivable_application_id is not secified


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:
  1. applied_payment_schedule_id must be -8

  2. Display flag = ‘Y' (latest application) and status = ‘ACTIVITY'

  3. Must correspond to the customer_trx_id specified.


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

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


Validation:
  1. It is valid if the following conditions are true:

    • The date is in an Open or Future period

    • The period cannot be an Adjustment period

  2. reversal GL date >= application GL date

  3. reversal GL date >= transaction GL date


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

Example

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 Enteredvalue DefaultValue
p_api_version 1.0  
p_receivable_application_id 10051  

This table lists the defaulted input parameters, which were not entered:

Parameter Entered Value Defaultvalue
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.

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