Home > Aria Crescendo Documentation > Aria Crescendo core api > create_advanced_service_credit_m

create_advanced_service_credit_m

This API creates service credit in advance on an account or master plan instance.

For information on error messages generated by this API, see create_advanced_service_credit_m Error Messages.

Input Arguments

Req Field Name Field Type Max Length Description
required-icon.png client_no long 22 Aria-assigned unique identifier indicating the Aria client providing service to this account.
required-icon.png auth_key string 32 Aria-assigned unique key to be passed with each method call for authenticating the validity of the requestor.
required-icon.png acct_no long 22 Aria-assigned account identifier. This value is unique across all Aria-managed accounts.
  OR      
  client_acct_id string 50 Client-defined account identifier.
  master_plan_instance_no long 22 The Master Subscription plan instance number.
  OR      
  client_master_plan_instance_id string 100 Client-defined Master plan Subscription plan instance ID.
  amount double 12 The amount of service credit to create on the account.
  reason_code long 22 The reason a given credit was/is to be applied to the account.  

Allowable values for reason_code:

Values Description
1 General Credit/Other
2 Inadequate Service Delivery
3 Billing / Pricing Issue
4 Service no longer desired
5 Customer Dissatisfaction
6 Installation Issue
9 Customer Return
11 System Testing
  comments string 300 Free form optional text up to 300 characters. For display within AdminTools when viewing all credit records on an account.
  eligible_plan_no (DEPRECATED) long 22 Eligible plan no or client eligible plan ID if the master plan instance number is passed. If the master plan instance no / client master plan instance ID parameter is not passed, this field is ignored. If the master plan instance no/client master plan instance ID is ignored, this field will be ignored. This parameter will be deprecated in the future.
  OR      
  client_eligible_plan_id (DEPRECATED) string 100 Eligible plan no or client eligible plan ID if the master plan instance number is passed. If the master plan instance no / client master plan instance ID parameter is not passed, this field is ignored. If the master plan instance no/client master plan instance ID is ignored, this field will be ignored. This parameter will be deprecated in the future.
  eligible_service_no (DEPRECATED) long 22 Eligible service no or client eligible service ID if eligible plan no or client eligible plan ID is passed. If the eligible plan no/client eligible plan ID is not passed, or is passed but is ignored, then this field will also be ignored. This parameter will be deprecated in the future.
  OR      
  client_eligible_service_id (DEPRECATED) string 100 Eligible service no or client eligible service ID if eligible plan no or client eligible plan ID is passed. If the eligible plan no/client eligible plan ID is not passed, or is passed but is ignored, then this field will also be ignored. This parameter will be deprecated in the future.
  alt_service_no_to_apply long 22 Under default conditions, when a service credit on an account is consumed (resulting in negative line items attached to account invoices) the service_no value used by Aria on those invoice line items is the "universal" Aria service_no for service credits, specifically "0". This results in financial reports which group charges by service_no putting all consumed service credits into the same service_no 0 "bucket". If the client wishes for this credit, once consumed, to go into any other service_no "bucket", that service_no must be supplied in this field. Any Aria-standard or custom-to-client service number may be used. A common (but not required) use of this field is in conjunction with the eligible_plan_no/eligible_service_no fields described above, e.g.: Client offers plan_no XXXX with a recurring fee of service_no YYYY. A credit is attached to an account (which has plan XXXX) specifying these two values in the "eligible_" fields described above, which means that the credit will be consumed as an offset against and plan XXXX/service YYYY charges incurred by the account holder. Additionally, the client provides value YYYY in this field, which means that when the service credit is consumed the negative line item it creates on the account holder's invoice will use the same service no as the charge it offsets. If the amount of the recurring fee for plan XXXX/service YYYY is $10 (resulting in a positive line item of $10 with service YYYY on their invoice), and if the amount of the credit line item is $5 (resulting in a negative line item of -$2 with service YYYY on their invoice) the net result in any financial report that groups by service_no will be $8 (as opposed to $10 in service YYYY and -$2 in service 0).
  OR      
  client_alt_service_id_to_apply string 100 Client-defined unique alternate service ID that is to be applied
  frequency_no long 8

Number of times the service credit should be applied to the account

You can pass in <frequency_no>,  <credit_expiry_months>, or <credit_expiry_date> (based on <credit_expiry_type_ind>), and <frequency_interval_type> to create a recurring service credit with an expiration month, week, day, or date.
  frequency_interval_months long 8 (Deprecated) Number of months between application of service credit to the account
  initial_credit_date string 14 Date on which the recurring service credit should start to be applied
  percent_amount double 12 The percent amount of the credit to be created for the account. For example if the account is to receive a 10% discount.
  percent_eval_plan_no long 22 (Deprecated) The plan number against which to apply the percent discount.
  OR      
  client_percent_eval_plan_id string 100 (Deprecated) The client-defined unique plan ID against which to apply the percent discount.
  percent_eval_service_no long 22 The service to which the percent discount is to be applied.
  OR      
  client_percent_eval_service_id string 100 The service to which the percent discount is to be applied.
  eligible_service_types string array 2 Service type code for which the credit is applicable.  

Allowable values for eligible_service_types:

Values Description
RC Recurring Service
US Usage Service
TX Tax Service
AC Activation Service
MS (DEPRECATED) Miscellaneous Service
CN Cancellation Service
OR Order Based Service
MN Minimum Fee Service
RA Recurring Arrears Service
SC Surcharge Service
  credit_expiry_type_ind string 1

Indicator which determines whether the credit expiration is based on months (<credit_expiry_months>) or a specific date (<credit_expiry_date>).

Note: If you pass in a <credit_expiry_type_ind>, then <credit_expiry_period> is required.

Allowable values for credit_expiry_type_ind:

Values Description
M Service credit expiration in months
W Service credit expiration in weeks
Y Service credit expiration in days
D Service credit expiration on specific date
  credit_expiry_months long 2

Total months after which service credit expires.

You can pass in frequency_no,  credit_expiry_months or credit_expiry_date (based on credit_expiry_type_ind), and frequency_interval_type to create a recurring service credit with an expiration month/date.

  credit_expiry_date string 10

The date on which credit expires. The date is in the format yyyy-mm-dd.

You can pass in frequency_no,  credit_expiry_months or credit_expiry_date (based on credit_expiry_type_ind), and frequency_interval_type to create a recurring service credit with an expiration month/date.

Note: The expiration date must be after the application date of the last service credit applied based on your specified frequency_no. Example: If you create a service credit to be applied in the next 2 months, the expiration date must be more than 2 months away.
Start of eligible_service_plans array
  eligible_service_plans array    
  Field Name Field Type Max Length Description
  brd_arrow.gifplan_no long 22 If used, specifies the plan(s) to which the credit is applied. If the credit is to be applied as an offset to ANY charge incurred by the account holder, leave this field empty. If the credit is to be applied to offset a specific type of charge, then this field and either the eligible_service_no or client_eligible_service_id field must be valued.
  brd_arrow.gifservice_no long 22 If used, specifies the service(s) to which the credit is applied. If you value this field, you must also value either the corresponding plan_no field. If the credit to be created is to be applied to offset a specific type of charge, then that specific plan_no and service_no combination referencing that type of charge must be supplied in these two fields.

If you use this array to enter multiple service numbers, you must enter the same number of plans in the plan_no array, and the plan number and its corresponding service number must appear in the same sequence in each array, or the API call fails.
End of eligible_service_plans array
 
Start of client_eligible_service_plan_ids
  client_eligible_service_plan_ids array    
  Field Name Field Type Max Length Description
  brd_arrow.gifclient_plan_id string 100 If used, specifies the plan(s) to which the credit is applied. If the credit is to be applied as an offset to ANY charge incurred by the account holder, leave this field empty. If the credit is to be applied to offset a specific type of charge, then this field and the client_service_id field must be valued.
  brd_arrow.gifclient_service_id string 100 If used, specifies the service to which the credit is applied. If you value this field, you must also value either the client_plan_id field. If the credit to be created is to be applied to offset a specific type of charge, then that specific client_plan_id and client_service_id combination referencing that type of charge must be supplied in these two fields.

If you use this array to enter multiple service numbers, you must enter the same number of plans in the client_plan_id array, and the client_plan_id and its corresponding client_service_id must appear in the same sequence in each array, or the API call fails.
End of client_eligible_service_plan_ids
 
  frequency_interval_type long 1

The unit of time associated with the frequency.

You can pass in <frequency_no>,  <credit_expiry_months>, or <credit_expiry_date> (based on <credit_expiry_type_ind>), and <frequency_interval_type> to create a recurring service credit with an expiration month/date.

Note: If you pass 6 (weekly) or 7 (daily) into this field,  then you must also pass in a <frequency_interval_length>.

Allowable values for frequency_interval_type:

Values Description
1 Monthly
2 Bi-monthly
3 Quarterly
4 Semi-annually
5 Annually
6 Weekly
7 Daily
Start of eligible_plan_instances array
  eligible_plan_instances array    
  Field Name Field Type Max Length Description
  brd_arrow.gifplan_instance_no long 22 Plan instance number.
  brd_arrow.gifplan_instance_service_no long 22 If used must be used in conjunction with field plan_instance_no. If the credit(s) to be created are to be applied as offsets to ANY charge incurred by the account holder, leave both of these fields empty. If the credit(s) to be created are to be applied as offsets to a specific type of charge, then that specific plan_instance_no and service_no combination referencing that charge are to be supplied in these two fields.
End of eligible_plan_instances array
 
Start of client_eligible_plan_instances array
  client_eligible_plan_instances array    
  Field Name Field Type Max Length Description
  brd_arrow.gifclient_plan_instance_id string 100 Client-defined unique eligible plan IDs.
  brd_arrow.gifclient_plan_instance_service_id string 100 Client-defined unique eligible service ids.
End of client_eligible_plan_instances array
 
  percent_eval_plan_instance_no long 22 The plan under this plan instance will be used to calculate the service credit.
  OR      
  client_percent_eval_plan_instance_id string 100 The plan under this client-defined unique plan instance ID will be used to calculate the service credit.
  service_code_option long 1 The value of this field will define which service will be used as a template for taxation on the service credit that is created.  

Allowable values for service_code_option:

Values Description
  If no value is entered in this field, the universal service will be used unless a value is entered in the alt_service_no_to_apply or client_alt_service_id_to_apply field. Then the referenced service will be used instead.
0 Aria's universal service will be used to apply this service credit which excludes taxes.
1 The service associated with this service credit can be selected using the alt_service_no_to_apply or client_alt_service_id_to_apply input fields. Tax handling for the service credit will reflect the settings for the service selected.
2 The service associated with this service credit will match the charge line item. This will result in tax handling that matches the original charge.
  alt_caller_id string 30 Person or process that submitted the API call. This can be someone's user ID, or the name of an application.
Start of optional_transaction_qualifiers array
  optional_transaction_qualifiers array   Array of additional values you can associate with this API call.
  Field Name Field Type Max Length Description
  brd_arrow.gifqualifier_name string 100 Name of the field you want to associate with this API call.
   brd_arrow.gifqualifier_value string 100 Corresponding value of the field you want to associate with this API call.
End of optional_transaction_qualifiers array
 
  credit_expiry_period long 3

Expiration of the credit in days, weeks, or months. Allowable values are 1-999.

To specify the credit expiration, pass a value into this field and the <credit_expiry_type_ind> field.

Example: If you pass Y (days) into the <credit_expiry_type_ind> field and 5 into the <credit_expiry_period> field, it means that the credit will expire 5 days after it is applied to an account.

Note:

  • This field is required if you passed in a <credit_expiry_type_ind>.
  • A specific date is not supported in this field. To specify the date on which a credit expires, use the <credit_expiry_date> field.
  frequency_interval_length long 3

Defines the duration between credits.

Example: If you pass 4 into this field and 6 (weekly) into the <frequency_interval_type> field, then the service credit will be applied every 4 weeks.

 

Note: This field is required if you passed 6 (weekly) or 7 (daily) into the <frequency_interval_type> field.
  application_id string 300 The application identifier in which the API is being used in. (Example: “Sales Force”)
  application_date string 300 The application date/timestamp, ie. 01/01/2014 10:00:00 to track when the application called the API.

Output Arguments

Field Name Field Type Description
error_code long Aria-assigned error identifier. 0 indicates no error.
error_msg string Description of any error that occurred. "OK" if there was no error.
Last modified

Tags

This page has no custom tags.

Classifications

This page has no classifications.
Powered by CXone Expert ®