assign_custom_acct_plan_rates_m Guide

Last updated
Save as PDF

The assign_custom_acct_plan_rates_m API applies custom rates to a particular plan instance and service assigned to a specified account.

API Specification:	assign_custom_acct_plan_rates_m
Required Fields:	<client_no> <auth_key> <acct_no> or <client_acct_id> <plan_instance_no> or <client_plan_instance_id> <custom_acct_rates> (array) <rate_seq_no>

Error Codes

Error Code/Description	Associated Inputs
1001: unexpected error
1004: authentication error	<auth_key>, <client_no>
1009: account does not exist, Account not found: AriaNo (acct_no), Account not found: Userid (userid), or Account not found: ClientId (client_acct_id)	<acct_no>, <client_acct_id>
1010: missing required parameters, Missing input: (object-name) is required with assignment_directive ($AriaNo)	<acct_no>
14005: invalid Plan service combination Additional Comments: The given Plan number and service number combination for master and Supplemental Plans is not valid.	<client_service_id>
14014: When entering custom rates, the end sequence number of one tier must immediately precede the start sequence number of the next tier. Alt: invalid rate tier structure Additional Comments: When entering custom rates, the tiers must be continuous, that is, the end sequence number of one tier must immediately precede the start sequence number of the next tier. In addition, the rate schedule must have the same number of units in each tier, and the same number of tiers, as the schedule on which it is based. From_units must be greater than - and less than to_units.	<custom_acct_rates> array fields
14015: The custom rates for services other than usage and recurring types can have only one tier with rate_seq_no set to 1, the from_unit set to 1 and to_unit left empty. Alt: custom from and to units not supported for given service_no Additional Comments: For the custom rate sequence, the "from" unit in one tier is not immediately after the end unit in the previous tier. Tiers are not allowed for other than recurring and usage services.	<custom_acct_rates> array fields
14027: The end units of final rate tier is not infinity Additional Comments: The custom rates final unit must be infinity.	<custom_acct_rates> array fields
14036: Invalid client service id	<client_service_id>
14043: Invalid Plan instance rate_seq combination Additional Comments: If the from/to units are not specified, the given rate_seq_no must be a valid rate_seq_no.	<custom_acct_rates> array fields
14046: If you passed in an invalid plan_instance_no, this message will appear: "Invalid Plan instance number". If you passed in an invalid master_plan_instance_id, this message will appear: "Invalid master_plan_instance_id". Additional Comments: The plan_instance_no or master_plan_instance_id must belong to the account, or it is invalid. The percent_eval_plan_instance_no must belong to the account and also to the MPI given in input.	<plan_instance_no>, <client_plan_instance_id>
14047: If you passed in an invalid client_plan_instance_id, this message will appear: "Invalid client Plan instance identifier". If you passed in an invalid client_master_plan_instance_id , this message will appear: "Invalid client_master_plan_instance_id".	<client_plan_instance_id>
14107: Invalid Service Number.	<service_no>
14129: Rate per unit cannot be negative.	<custom_acct_rates> array fields

Additional Guidance

Input Fields

Field Name

Notes

<plan_scope>

This determines whether the rate changes apply to a current plan or a queued (future) plan.

If a customer has a future plan that is already scheduled to be assigned after a rollover from a currently-assigned plan, you can assign custom rates to the future plan. This applies to a future plan assignment set up by:

scheduling a plan change to go into effect on the customer's anniversary date using assignment_directive=1 or master_plan_assign_directive=1 in an API that supports either of those fields (examples: assign_acct_plan_m or update_acct_complete_m); or

adding a subscription to a plan scheduled to roll over to another plan on the customer's anniversary date; or

adding a subscription to a plan scheduled to roll over to another plan on any other chosen date.

Example: You may choose to offer a customer a promotional rate for a future plan as a goodwill gesture or for other business reasons.

To assign custom rates to a future plan, pass values into the plan_scope and plan_queue_id fields.

The plan_queue_id is not required for custom rates that will be applied to a future plan scheduled to be assigned on the customer's anniversary date.

The plan_queue_id input will be ignored if you do not pass Q into the plan_scope field.

Allowable values:

Values	Description
C	The specified custom rates should be applied to the current plan (default).
Q	The specified custom rates should be applied to the queued (future) plan. The plan_queue_id input will be ignored if you do not pass Q into the plan_scope field.

<api_queue_detail>

When a custom rate queue is updated by providing a future queue ID, and the future queue contains the parameter <custom_rate_client_service_id> and its value is converted to the corresponding service number and stored as <custom_rate_service_no> field in the <api_queue_detail> table. This conversion process is logged in the <acct_comments_hist> table for future reference with the following message:

"Queue ID <<queueid>> has been updated to convert the param custom_rate_client_service_id to custom_rate_service_no for the plan instance <<pi>> by the system."

<custom_rates_directive>

Allows you to modify the custom rate tiers to be fewer than the original custom rate tiers.

The <custom_rates_directive> parameter governs whether to remove the existing custom rates when assigning new custom rates. The default value is '1' and leaves the existing custom rates in place. A value of '2' will remove the custom rates and honor the custom rates passed.

Allowable values:

Values	Description
1 / NULL	(Default) Leaves the existing custom rates in place and honors the custom rates passed.
2	Removes the existing custom rates and honors the custom rates passed.