Skip to main content
Aria Knowledge Central

modify_acct_plan_unit_instances_m

Summary

API Name modify_acct_plan_unit_instances_m
Class account_services_m
Update Version 53

Description

Use this API to assign a new Plan Unit Instance to a specified plan, or to remove a Plan Unit Instance from a specified plan. The do_write input variable option on this API, allows for the previewing of charges for the desired units modification.

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

plan_inst_no long 22 Yes

The unique identifier of the new plan replacing the existing plan on the instance.

Alternative required field: client_plan_inst_id

client_plan_inst_id string 100 Yes

The client-defined identifier of the new plan replacing the existing plan on the instance.

Alternative required field: plan_inst_no

remove_plan_units object   No

Array of plan units associated with this account. This remove action has precedence over adding units. Thus, if this array is present, then new_plan_units to add will be ignored.

See fields below

assignment_directive long 2 No

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.

Allowed values:

Value Description
1 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 invoice/charges 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 invoice/charges 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 invoice/charges 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.
5 Perform the requested plan change immediately, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing PRORATION FOR CHARGES ONLY. NOTE: This value is not permitted when cancelling supplemental plans.
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 invoice/charges 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 invoice/charges 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.
10 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 CHARGES ONLY. NOTE: This value is not permitted when cancelling a supplemental plan.
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.
new_plan_units double 12 No

Number of additional units of the specified plan to be assigned to the account

new_client_plan_unit_inst object   No

Array of Client-defined ID associated with the plan unit of the account

See fields below

proration_invoice_timing long 1 No

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.

Allowed values:

Value 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.
do_write string 5 No

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'

Allowed values:

Value Description
True  
False  
recurring_processing_model_ind long 1 No

Defines a recurring payment type for Credit Card and Tokenized Credit Cards. A null value will default to 0 - Cardholder-Initiated Transaction - Credentials on File.

Allowed values:

Value 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.
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.

remove_plan_units fields

Name Type Length Required Description
plan_unit_inst_no long 22 No

The unique identifier of the plan unit instance to be removed. This API expects all plan unit instances to be for the same plan_inst_no, or client_plan_inst_id.

Alternative field: client_plan_unit_inst_id

client_plan_unit_inst_id string 100 No

The client-defined identifier of the plan unit instance to be removed. This API expects all plan unit instances to be for the same plan_inst_no, or client_plan_inst_id.

Alternative field: plan_unit_inst_no

new_client_plan_unit_inst fields

Name Type Length Required Description
new_client_plan_unit_inst_id string 100 No

Client-defined ID to be used for a given plan unit being assigned to the account.

Outputs

Name Type Length Required Description
error_code long   No

Aria-assigned error identifier. 0 indicates no error.

error_msg string   No

Textual description of any error that occurred. "OK" if there was no error.

proration_result_amount double   No

The currency amount of any resulting proration action performed as a result of the requested plan change. For plan assignments with an assignment directive of '1' (perform on anniversary date), or '2' (honor client default proration action) when the default configuration is to not do proration, or '3' (force no proration), the value returned in this field will always be '0'. When proration is performed the value returned in this field will either be a positive currency value (indicating a resulting charge to the account) or a negative currency value (indicating a credit to the account). If the value passed in field do_write is false then any positive or negative value returned in this field is notational only, demonstrating what proration effect would be applied to the account if the requested plan assignment/de-assignment were to be actually performed.

collection_error_code long   No

If a collection is attempted, returns the error code associated with the collection.

collection_error_msg string   No

The error message associated with collection_error_code.

statement_error_code long   No

The error code if statement generation fails.

statement_error_msg string   No

The text message associated with 'statement_error_code'

proc_cvv_response string   No

The processor return code from CVV validation.

proc_avs_response string   No

Processor return code from address validation

proc_cavv_response string   No

The processors return code for security validation.

proc_status_code string   No

The processor status code

proc_status_text string   No

The processors status description

proc_payment_id string   No

The processor payment ID

proc_auth_code string   No

Authorization code provided by the issuing bank

proc_merch_comments string   No

Additional information passed to payment processor

proc_initial_auth_txn_id string 100 No

Transaction ID from payment processor. If received as part of an auth request, it must be retained for future settlement and match the value from the auth response. It should also be used for future recurring transaction auths/settlement.

cancelled_supp_plans object   No

An array containing the supplemental plans cancelled.

See fields below

invoice_no long   No

The Aria-assigned unique identifier of a given invoice.

expectd_activation_fee double   No

The activation fee the account holder can expect based on the activation fees of the plans on this invoice

expectd_mthly_recurring_cost double   No

Regardless of the billing interval on the account, the monthly recurring cost of this change

expectd_annu_recurring_cost double   No  
invoice_line_items object   No

See fields below

invoice_line_item object   No

Note: This field is deprecated. Aria no longer supports invoice_line_item.

total_charges_before_tax double   No

Total amount to be charged to the account before taxes have been calculated.

total_tax_charges double   No

Total taxes as calculated for the amount of the transaction.

total_charges_after_tax double   No

Total amount to be charged to the account after taxes have been calculated.

total_credit double   No

The total amount of the credit to be applied to the account

total_tax_credit double   No

The tax amount of the credit to be applies

total_credit_before_tax double   No

The credit to be applied before tax is taken into account

total double   No

The grand total of this invoice

proration_credit_result_amount double   No

The total pro-rated credit amount

proration_credit_amount double   No

The non-tax pro-rated credit amount

proration_tax_amount double   No

The pro-rated tax credit amount

proc_payment_response_field_list object   No

Payment response fields returned by the processor for further actions if any.

See fields below

cancelled_supp_plans fields

Name Type Length Required Description
supp_plan_no long   No

The unique ID of the supplemental plan

supp_plan_name string   No

The name of the supplemental plan

supp_proration_result_amount double   No

The result of the proration calculation for the unused portion of the billing period

client_supp_plan_id string 100 No

Client-defined supplemental plan ID.

invoice_line_items fields

Name Type Length Required Description
units     No  
amount     No  
base_plan_units     No  

proc_payment_response_field_list fields

Name Type Length Required Description
proc_payment_response_field_name string 100 No

Field name of various response returned by the processor, example: micro_deposit_verify_url.

Allowed values:

Value Description
micro_deposit_verify_url The URL returned by the processor to share with the customer to validate their bank information and perform the micro deposits.
proc_payment_response_field_value string 4000 No

Field value for the corresponding payment response field, example: Actual URL to be used for the micro deposit verification.

TOP
  • Was this article helpful?