create_advanced_service_credit_m
Summary
| API Name | create_advanced_service_credit_m |
|---|---|
| Class | account_services_m |
| Update Version | 61 |
Description
Creates an advanced service credit on an account or a specific master plan instance (MPI). Service credits differ from cash credits in that they reduce charges at the service/plan level during invoice generation rather than applying monetary adjustments against existing invoice balances. Service credits are consumed automatically when the next invoice is generated for the plan instance.Advanced service credits offer more configuration than basic service credits:
- Can be scoped to a specific master plan instance or applied at the account level
- Support both one-time and recurring credit schedules
- Can specify eligible services that the credit applies to (rather than all services)
- Can include reason codes for audit tracking
- Can be set with expiration dates
Use this API when you need to provide account credits that offset future billing amounts — for example, as compensation for service outages, promotional credits, or migration incentives. To apply a monetary credit against existing outstanding invoices instead, use apply_cash_credit_m from the Transaction Services API. To view existing credits on an account, use get_acct_credits_m.
Inputs
| Name | Type | Length | Required | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| client_no | long | 22 | Yes |
Aria-assigned unique identifier indicating the Aria client providing service to this account. |
||||||||||||||||||
| auth_key | string | 32 | No |
Aria-assigned unique key for authenticating the validity of the requestor. This key is passed with each method call. |
||||||||||||||||||
| acct_no | long | 22 | Yes |
Aria-assigned account identifier. This value is unique across all Aria-managed accounts. Alternative required field: client_acct_id |
||||||||||||||||||
| client_acct_id | string | 50 | Yes |
Client-defined account identifier. Alternative required field: acct_no |
||||||||||||||||||
| master_plan_instance_no | long | 22 | No |
The Master Subscription plan instance number. Alternative field: client_master_plan_instance_id |
||||||||||||||||||
| client_master_plan_instance_id | string | 100 | No |
Client-defined Master plan Subscription plan instance ID. Alternative field: master_plan_instance_no |
||||||||||||||||||
| amount | double | 12 | No |
The amount of service credit to create on the account. |
||||||||||||||||||
| reason_code | long | 22 | No |
The reason a given credt was/is to be applied to the account. Allowed values:
|
||||||||||||||||||
| comments | string | 300 | No |
Free form optional text up to 300 characters. For display within AdminTools when viewing all credit records on an account. |
||||||||||||||||||
| eligible_plan_no | long | 22 | No |
Note: This field is deprecated. Aria no longer supports eligible_plan_no. |
||||||||||||||||||
| eligible_service_no | long | 22 | No |
Note: This field is deprecated. Aria no longer supports eligible_service_no. |
||||||||||||||||||
| alt_service_no_to_apply | long | 22 | No |
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). Alternative field: client_alt_service_id_to_apply |
||||||||||||||||||
| frequency_no | long | 8 | No |
Number of times the service credit should be applied to the account |
||||||||||||||||||
| frequency_interval_months | long | 8 | No |
Note: This field is deprecated. Aria no longer supports frequency_interval_months. |
||||||||||||||||||
| initial_credit_date | string | 14 | No |
Date on which the recurring service credit should start to be applied |
||||||||||||||||||
| percent_amount | double | 12 | No |
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 | No |
Note: This field is deprecated. Aria no longer supports percent_eval_plan_no. |
||||||||||||||||||
| percent_eval_service_no | long | 22 | No |
The service to which the percent discount is to be applied. Alternative field: client_percent_eval_service_id |
||||||||||||||||||
| eligible_service_types | object | No |
A list of eligible service types |
|||||||||||||||||||
| client_eligible_plan_id | string | 100 | No |
Note: This field is deprecated. Aria no longer supports client_eligible_plan_id. |
||||||||||||||||||
| client_eligible_service_id | string | 100 | No |
Note: This field is deprecated. Aria no longer supports client_eligible_service_id. |
||||||||||||||||||
| client_alt_service_id_to_apply | string | 100 | No |
Client-defined unique alternate service ID that is to be applied Alternative field: alt_service_no_to_apply |
||||||||||||||||||
| client_percent_eval_plan_id | string | 100 | No |
Note: This field is deprecated. Aria no longer supports client_percent_eval_plan_id. |
||||||||||||||||||
| client_percent_eval_service_id | string | 100 | No |
The service to which the percent discount is to be applied. Alternative field: percent_eval_service_no |
||||||||||||||||||
| credit_expiry_type_ind | string | 1 | No |
Indicator which determines the expiry is based on months or till Specific Date. Allowed values:
|
||||||||||||||||||
| credit_expiry_months | long | 2 | No |
Total Months after which service credit expires. |
||||||||||||||||||
| credit_expiry_date | string | 10 | No |
The date on which credit expires. The date is in the format yyyy-mm-dd. |
||||||||||||||||||
| eligible_service_plans | object | No | ||||||||||||||||||||
| client_eligible_service_plan_ids | object | No | ||||||||||||||||||||
| frequency_interval_type | long | 1 | No |
The unit of time associated with the frequency. Allowed values:
|
||||||||||||||||||
| eligible_plan_instances | object | No | ||||||||||||||||||||
| client_eligible_plan_instances | object | No | ||||||||||||||||||||
| percent_eval_plan_instance_no | long | 22 | No |
The plan under this plan instance will be used to calculate the service credit. Alternative field: client_percent_eval_plan_instance_id |
||||||||||||||||||
| client_percent_eval_plan_instance_id | string | 100 | No |
The plan under this client-defined unique plan instance ID will be used to calculate the service credit. Alternative field: percent_eval_plan_instance_no |
||||||||||||||||||
| service_code_option | long | 1 | No |
The value of this field will define which service will be used as a template for taxation on the service credit that is created. Allowed values:
|
||||||||||||||||||
| credit_expiry_period | long | 3 | No |
The value of this field will define the max length of applicable service credits that supports daily, weekly and monthly (exclude: specific date). And should be used with credit_expiry_type_ind. |
||||||||||||||||||
| frequency_interval_length | long | 3 | No |
The value of this field will accommodate Monthly, Daily and Weekly and will to be used in tandem with frequency_interval_type. It defines interval of recurring service credits. |
eligible_service_types fields
| Name | Type | Length | Required | Description | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| eligible_service_types | string | 2 | No |
Service type code for which the credit is applicable. Allowed values:
|
eligible_service_plans fields
| Name | Type | Length | Required | Description |
|---|---|---|---|---|
| plan_no | long | 22 | No |
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. |
| service_no | long | 22 | No |
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. |
client_eligible_service_plan_ids fields
| Name | Type | Length | Required | Description |
|---|---|---|---|---|
| client_plan_id | string | No |
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. |
|
| client_service_id | string | No |
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. |
eligible_plan_instances fields
| Name | Type | Length | Required | Description |
|---|---|---|---|---|
| plan_instance_no | long | 22 | No |
Plan instance number. |
| plan_instance_service_no | long | 22 | No |
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. |
client_eligible_plan_instances fields
| Name | Type | Length | Required | Description |
|---|---|---|---|---|
| client_plan_instance_id | string | 100 | No |
Client-defined unique eligible plan IDs. |
| client_plan_instance_service_id | string | 100 | No |
Client-defined unique eligible service ids. |
Outputs
| Name | Type | Length | Required | Description |
|---|---|---|---|---|
| error_code | long | No |
Aria-assigned error identifier. 0 indicates no error. |
|
| error_msg | string | No |
Description of any error that occurred. "OK" if there was no error. |
|
| credit_id | long | No |
Aria-assigned unique identifier. |
|
| recurring_credit_no | long | No |
The identifier for the recurring credit. |