cancel_acct_plan_m Guide

Last updated
Save as PDF

Cancels a master or supplemental plan assigned to a specified account. Note that the cancellation of a master or supplemental plan also cancels all its child plans. These child plans however, remain on the account in an unusable state in the event the parent plan is re-activated. When all master plans on an account have a plan status of Cancelled, Terminated or Suspended, the account will be automatically deactivated based on the Days Before Deactivation configuration parameter.

API Specification:	cancel_acct_plan_m
Required Fields:	<client_no> <auth_key> <acct_no> or <client_acct_id> <plan_instance_no> or <client_plan_instance_id>

Additional Guidance

Input Fields

Field Name:

Notes:

<assignment_directive>

The rule to be applied to this assignment request, governing the proration rule is applied. Default behavior is to make the plan change (assign/deassign a plan to an account, change units on an existing plan, etc.) immediately based on client-defined default proration rule, resulting in appropriate prorated charge and credit. Usage-arrears charges, recurring-in-arrears charges, and any plan cancellation fees (if applicable) will be invoiced during plan cancellation, as these charges are independent of assignment directive.

Allowable values:

Values	Description
1	(Default) Perform the requested plan change on the account's next scheduled billing anniversary date. The account does receive service under this plan (for plan assignments) or have it removed (for de-assignments) until that date. If a plan is being assigned, initial billing for a full period of the given plan is performed on the account's next scheduled anniversary date. No charge or credit proration effect. No new recurring charges or credits are generated when no proration occurs.
2	Perform the requested plan change immediately, honoring the client's pre-configured universal rule for performing or not performing proration as a result of a mid-billing-period plan assignment or de-assignment. No new recurring charges or credits are generated when no proration occurs. (default)
3	Perform the requested plan change immediately, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing NO PRORATION. No new recurring charges or credits are generated when no proration occurs.
4	Perform the requested plan change immediately, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing PRORATION.
6	Perform the requested plan change immediately, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing PRORATION FOR CREDITS ONLY. NOTE: This value is not permitted when assigning supplemental plans.
7	Perform the requested plan change on the specified effective_date, honoring the client's pre-configured universal rule for performing or not performing proration as a result of a mid-billing-period plan assignment or de-assignment. No new recurring charges or credits are generated when no proration occurs.
8	Perform the requested plan change on the specified effective_date, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing NO PRORATION. No new recurring charges or credits are generated when no proration occurs.
9	Perform the requested plan change on the specified effective_date, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing PRORATION.
11	Perform the requested plan change on the specified effective_date, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing PRORATION FOR CREDITS ONLY. NOTE: This value is not permitted when assigning a supplemental plan.

<alt_proration_start_date>

If you cancel a Master Plan or Supplemental Plan using this API, the <alt_proration_start_date> must be within the date range of the recurring billing period that was last invoiced.

<invoice_unbilled_usage>

Specifies whether to invoice the unbilled usage if a plan is terminated in the middle of a billing period.

Allowable values:

Values	Description
false	Do not allow invoicing the unbilled usage during mid-term plan termination.
true	Allow invoicing the unbilled usage during mid-term plan termination.

<do_write>

Boolean indicator that specifies whether to actually perform the requested operation. If 'false' is passed in this field, Aria calculates, if applicable, any potential effects from this call such as proration, plan assignments, etc. and return all relevant data without actually performing the requested operation or making any changes to the account. This is useful to interfaces that want to present the user with a 'confirmation page' informing them of the potential effects of the requested operation prior to actually performing it. Do_write defaults to 'true'

Allowable values:

Values	Description
true	true
false	false

<proration_invoice_timing>

Determines whether to create a separate invoice for prorated charges immediately, or defer to the next anniversary date. Note that this will override the Proration Invoice Timing configuration saved with the plan in the product catalog.

Allowable values:

Values	Description
Null (default)	Honor Proration Invoice Timing configuration saved with the plan in the product catalog.
0	Indicates to generate the invoice immediately for the pro-rated charges.
1	Indicates to generate the invoice to the next anniversary date for the pro-rated charges.

<recurring_process_model_ind>

Defines a recurring payment type for Credit Cards and Tokenized Credit Cards.

Allowable values:

Values	Description
0	Cardholder-Initiated Transaction – Credentials on File: a credit card transaction initiated by the cardholder for a new order or a plan upgrade that uses a credit card that is currently stored in Aria. (Default)
1	Cardholder-Initiated Transaction: a credit card transaction initiated by the cardholder for a new account or creating an order that uses an alternate credit card that is not currently stored in Aria.
2	Merchant-Initiated Transaction – Standing Instruction – Recurring: a credit card transaction initiated by Aria’s clients for a recurring charge that uses a credit card that is currently stored in Aria.
3	Merchant-Initiated Transaction – Unscheduled Credentials on File: a credit card transaction initiated by Aria’s clients for a non-recurring charge (one-time order or plan upgrade) that uses a credit card that is currently stored in Aria.

<include_plan_instance_queue>

Use this field to obtain the list of plan changes that you scheduled using this API.

Allowable values:

Values	Description
false	Scheduled plan changes will not be returned in the plan_instance_queue array (default).
true	Scheduled plan changes will be returned in the plan_instance_queue array.

Output Field

Field Name:

Notes:

<line_type>

Specifies the type of charge or credit associated with this line item.

Allowable values:

Values	Description
1	Recurring Charge
2	Tax Charge
3	Service Credit
4	Coupon Credit
5	Activation Charge
6	Usage Charge
7	Recurring Arrears
8	Order Charge
9	Surcharge

Error Codes

Error Code/Description	Associated Inputs
1001: unexpected error
1004: authentication error Associated Inputs: auth_key, client_id, client_no	<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) Associated Inputs: acct_no, account_no, client_acct_id, user_id, userid, parent_acct_no	<acct_no>, <client_acct_id>
25020: Illegal characters entered Associated Inputs: All character field inputs like firstname lastname, dunning_group_name, comments, etc.	All character field inputs like <client_no>, <acct_no>, <offset_interval>, etc.
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". Associated Inputs: plan_instance_no, master_plan_instance_id, filter_plan_instance_no, percent_eval_plan_instance_no, client_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". Associated Inputs: client_plan_instance_id, client_master_plan_instance_id, client_percent_eval_plan_instance_id	<client_plan_instance_id>
14070: Cannot cancel Plan which is under dunning Associated Inputs: existing_plan_instance_no	<plan_instance_no>
1024: invalid date format Associated Inputs: bill_birthdate, birthdate, degrade_date, initial_credit_date, invoice_line_reversing_date, service_fulfillment_date, queue_date, start_bill_date, end_bill_date, start_date, end_date, stmt_birthdate, bill_birthdate Additional Comments: All date inputs must be in yyyy-mm-dd format.	<application_date>, <alt_proration_start_date>, <effective_date>
1033: a parameter that represents a true or false value contains invalid input Associated Inputs: alt_collect_on_approve, alt_send_statement_on_approve, cancel_orders_on_discard, cascade_action, do_auto_discard, do_collect, change_status_after_coll, reset_dates_after_status, disable_existing_on_update, do_write, exclude_terminated_plan_inst, include_all_rate_schedules, include_plan_hierarchy, retrieve_bundled_nso, retrieve_included_nso, include_translations, include_inactive_items, include_invoice_activity_eligibility, include_rs_summary, include_translations, include_service_supp_fields/include_product_fields/, include_plan_instance_fields/include_plan_services/, include_surcharges, include_void_transactions, include_voided, invoice_unbilled_usage, is_unlinked_refund, record_cc_on_auth_failure, retrieve_excluded_usage, send_email, usage_pooling, do_write	<do_write>, <include_plan_instance_queue>
14023: Offset Interval must be greater than zero Associated Inputs: offset_interval	<offset_interval>
14024: Invalid Offset Interval and Assignment Directive combination. Associated Inputs: offset_interval, assignment_directive Additional Comments: Offset_interval only applies to the anniverary date.	<offset_interval>, <assignment_directive>
14025: Invalid do_write and assignment directive combination for queuing Plan. Associated Inputs: assignment_directive, do_write Additional Comments: Preview cannot be done for queued anniversary date cases.	<assignment_directive>, <do_write>
14026: The Effective Date must be in the future, "YYYY-MM-DD" format, and a valid date. Associated Inputs: effective_date	<effective_date>
1016: invalid input, acct_no: (acct_no) is not a valid long, assignment_directive: (assignment_directive) is not a valid long, “billing_group_no: (billing_group_no) is not a valid long, threshold_billing_rule_no: (threshold_billing_rule_no) is not a valid long Associated Inputs: alt_service_no_to_apply, assignment_directive, auto_skip_to_next_bill_date, client_billing_group_id, custom_rate_service_no/custom_rate_client_service_id, plan_instance_no, plan_instance_service_no, client_plan_instance_id, client_plan_instance_service_id, plan_instance_no, plan_instance_service_no, client_plan_instance_id, client_plan_instance_service_id, plan_instance_service_no, eligible_plan_no, eligible_service_no, email, force_master_bill_date_reset, fulfillment_only, include_master_plans, include_supp_plans, include_billing_groups, include_payment_methods, include_master_plans, include_supp_plans, include_billing_groups, include_payment_methods, invoice_no, length_months, end_date, limit, limit_records, modify_directive, contract_plan_instances_update, modify_directive, contract_plan_instances_update, offset, percent_amount, percent_eval_plan_instance_no, client_percent_eval_plan_instance_id, percent_eval_service_no, client_percent_eval_service_id, phone_ext, work_phone_ext, plan_unit_inst_status_cd, plan_units, reason_code, start_date, end_date, start_date, end_date, status_cd, acct_no, assignment_directive, billing_group_no, threshold_billing_rule_no Additional Comments: This error can be caused by the wrong type of input, for example, text in a numbers-only field, an or specifying a value other than one of the documented allowable values. For the get_order_m API, this is the error code returned when the user passes an invalid order value for the <status_filter_cd> input which is other than the allowed values (0/null, 1, 2, 3, 4 and 5). For the bulk_cancel_order_m API, invalid input can occur with the <order_status_directive> argument. Allowed values are 0, 1, 2, 3, 4/null, 5 and 6. For the get_acct_coupon_details_m API, invalid input can occur with the <include_all_active> input parameter (values are 0, 1 or NULL). Alternate Message Output 1016: username cannot be longer than 30 characters 1016: first_name cannot be longer than 30 characters 1016: last_name cannot be longer than 30 characters Associated APIs: create_user_m, update_user_m Associated Inputs: username, first_name, last_name	<plan_instance_no>, <client_plan_instance_id>, <acct_no>, <assignment_directive>
14098: Invalid proration invoice timing Associated Inputs: mp_proration_invoice_timing, proration_invoice_timing	<proration_invoice_timing>
14017: invalid alternate proration start date Alt: Date must be in YYYY-MM-DD format Associated Inputs: alt_proration_start_date Additional Comments: The alt_proration_start_date must be within the last billed period.	<alt_proration_start_date>
14081: Plan instance already cancelled Associated Inputs: existing_plan_instance_no	<plan_instance_no>
14088: Mandatory child Plans cannot be canceled unless their parent Plan is also canceled.
14112 Cannot update/replace/cancel any queued Plan instance which is in queued assignment Associated Inputs: plan_instance_no, client_plan_instance_id	<plan_instance_no>, <client_plan_instance_id>
3003: could not create invoice Additional Comments: Could not create a preview invoice due to account status, plan status, or other processing error. Please contact Aria Customer Support.