Skip to main content
Knowledge Central
Aria Knowledge Central

update_acct_plan_multi_m Guide

  1. Last updated
  2. Save as PDF

Assigns, replaces, updates, and/or cancels multiple plans (both master and supplemental plans) for a specified account.

In addition to plan assignment, you can also make the following plan changes:

  • Assign billing groups, dunning groups and collection groups
  • Assign a promotion code or a coupon
  • Change the number of plan unit instances assigned to an account
  • Assign services
  • Change the plan's fulfillment date
  • Assign standard and custom rate schedules
  • Assign surcharges
  • Assign a dunning state
  • Assign the responsibility level (parent, self-pay, etc.)
  • Assign proration and invoicing options
  • Reset billing dates
  • Enable usage pooling
  • Assign NSO items and their billing options
  • Assign payment terms or methods

You can assign, update, modify, and cancel multiple plans in a single API call. However, each plan instance can only be given one operation per call, i.e., you cannot update and cancel the same plan instance within the same call.

If you want to add new master plans to an existing account, and align the new plan's anniversary date with the existing plans, you can use the override_dates_mp_instance_no field.

When adding or replacing supplemental fields on an existing account, you can align the anniversary date to its master plan instance with the auto_offset_months field.

When adding, replacing and canceling a plan, you can use the alt_proration_start_date field to align the start dates of all the affected plans on the account.

Any field on a plan can be updated. You can clear the value in any field with a type of "string", provided that the field is nullable for a plan, by entering a '~' in that field.

API Specification: update_acct_plan_multi_m
Required Fields:
  • <client_no>
  • <auth_key>
  • <acct_no> or <client_acct_id>
  • <plan_updates> (array)
    • <plan_updates>
    • <plan_directive>
Error Messages: update_acct_plan_multi_m Error Messages

Additional Guidance

  • If you assign a Supplemental Plan at the same time as its Master Plan and provide an override bill through date, the bill through date for the Supplemental Plan is determined based on your setting for the parameter Override Bill Thru Date Supp Plan Behavior.

    To see a description of the parameter, click Configuration >Billing > Invoice Settings.
  • To determine the Master Plan's bill day when the update_acct_plan_multi_m API is called, Aria considers the following inputs in the order listed below:
    1. <override_bill_thru_date>;
    2. then whichever of these you passed in: <alt_start_date> or <alt_bill_day>;
    3. then whichever of these you passed in: <retroactive_start_date> or <effective_date>.
  • This API performs a maximum of 100 Plan updates in a single call.
Input Fields
Field Name: Notes:
<dunning_state>
  • If you set this field to 1(in progress), then you can specify one or more of the following dunning options available in these fields:
    • <degrade_date>;
    • <new_dunning_step>;
    • <config_dunning_late_fee_option>; and/or
    • <config_dunning_email_option>.
  • When you change the <dunning_state> to 0(none), you should also pass in your chosen <plan_status_cd> for the Master Plan Instance.

    Example: you may want to change the Master Plan Instance's status from
    -1 (suspended) to 1 (active).
  • If you set this field to 1(in progress) but the Master Plan Instance does not have a balance due, then Aria will move the Master Plan Instance out of dunning on the date on which the next dunning step begins.

    This applies to Master Plan Instances associated with either payment type: net terms or electronic.
  • In addition to self-pay Master Plan Instances, dunning input arguments can now also now be used for parent-pay Master Plan Instances. Also note that when self-pay Master Plan Instance manually enters dunning via this API, all of their parent-pay Master Plan Instances will enter dunning. This is only applicable when entering the dunning. During this special process of entering parent-pay Master Plan Instance, the “config_dunning_late_fee_option and config_dunning_email_option” will only be applicable for self-pay Master Plan Instances and NOT to the parent-pay Master Plan Instance.
Allowable Values
Values Description
0 None
1 In Progress
  • <billing_group_no>
  • <client_billing_group_id>
  • <billing_group_idx>
 This is mandatory when converting an Master Plan Instance from parent-pay to self-pay.
  • <dunning_group_no>
  • <client_dunning_group_id>
 You must associate a dunning group with parent-pay Master Plan Instances. If you do not specify a dunning group, Aria will automatically create an empty dunning group (without any attributes) and assign it to that Master Plan Instance.
<alt_proration_start_date>
  • If you assign a Supplemental Plan using this API, the <alt_proration_start_date> must be between the Master Plan’s provision date and the next occurrence of a bill day.
  • The <alt_proration_start_date> can also go back more than one billing period into the past as long as it is after the Master Plan’s provision date.
  • If you replace a Master Plan using this API:
  • When the replaced Master Plan’s billing interval is the same as the new Master Plan’s, the <alt_proration_start_date> must be within the date range of the recurring billing period that was last invoiced.
  • When the replaced Master Plan’s billing interval is different from the new Master Plan’s, the <alt_proration_start_date> must be between the start date of the recurring billing period that was last invoiced and the next occurrence of a bill day.
  • If you cancel a master 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.
  • <primary_payment_method_no>
  • <primary_client_payment_method_id>
  • <primary_payment_method_idx>
  • <backup_payment_method_no>
  • <backup_client_payment_method_id>
  • <backup_payment_method_idx>
 The same pay method sequence number cannot be used for a primary and secondary payment method.
<collection_group_bg_row>

Aria will use this order of precedence when selecting the payment gateway to use for processing a payment:

  1. Collection group assigned to the billing group associated with the master plan instance being invoiced;
  2. Collection group to which the customer is assigned at the account level.

Aria allows accounts to have multiple billing groups with different collection groups when using tokenized credit cards that were tokenized outside of Aria. To facilitate multiple payment methods, the billing agreement ID (token) is validated against the specific collection group. When there is no collection group specified, then the agreement ID will be validated against the account level collection group. When no collection group at account level or billing group level is specified, then the agreement ID will be validated against the last processor mapped to that client.
<new_dunning_step>

Applicable only for Master Plans, and only if the <dunning_state> is set to 1.

For more information about available dunning options, please see the <dunning state> field.
<config_dunning_late_fee_option>

Applicable only for Master Plans, and only if the <dunning_state> is set to 1.

For more information about available dunning options, please see the <dunning state> field.

If you set this field to 1, Aria will immediately charge the customer the late fee.
<config_dunning_email_option>

Applicable only for Master Plans, and only if the <dunning_state> is set to 1.

For more information about available dunning options, please see the <dunning state> field.

If you set this field to 1, Aria will immediately email the notification to the customer.
  • <resp_master_plan_instance_no>
  • <resp_client_master_plan_instance_id>
 Required if the responsibility level (in the <resp_level_cd> field) is set to one of the two parent pay options.

<proc_field_override> (array)

  • <transaction_type>

This field applies to credit cards and tokenized credit cards. If you don't pass a value into this field, it will default to -1 (use client configuration settings).

The value that you pass into this field will override the Recurring Options that you set in the Aria application under:

  • Configuration > Payments > Payment Gateways > Chase Paymentech/Vantiv> Gateway Options; and
  • Configuration > Payments > Collection Groups > Chase Paymentech/Vantiv > Collection Group Options.

Currently, only Chase Paymentech and Vantiv support this field. Other payment gateways might not honor all of the allowable values for this field. You will need to check your payment gateway documentation for confirmation.

Aria will use this order of precedence to determine the transaction type:

  1. value passed into this field
  2. collection group configuration
  3. payment gateway configuration
  4. transaction type that you specified in the <recurring_processing_model_ind> field
Allowable Values
Values Description
-1 Use client configuration settings for "Send Transaction Type as Recurring for Initial Request Where Possible" or "Send Transaction Type as Recurring for Subsequent Request" as applicable. (default)
1 (Chase) Single transaction mail/telephone order (MOTO) - Designates a transaction where the accountholder is not present at a merchant location and completes the sale over the phone or through the mail. The transaction is not for recurring services or products and does not include sales that are processed via an installment plan.
2 (Chase) Recurring Transaction - Designates a transaction that represents an arrangement between an accountholder and the merchant where transactions are going to occur on a periodic basis.
3 (Chase) Installment Transaction - Designates a group of transactions that originated from a single purchase where the merchant agrees to bill the accountholder in installments.
4 (Chase) Deferred Transaction - Designates a transaction that represents an order with a payment delayed for a specified amount of time.
5 (Chase) Secure Electronic Commerce Transaction - Designates a transaction completed via the Internet at a 3-D Secure capable merchant and in which the accountholder was fully authenticated. (examples: 3-D Secure includes Verified by Visa, Mastercard Identity Check, American Express SafeKey and Discover ProtectBuy.)
6 (Chase) Non-Authenticated Electronic Commerce Transaction - Designates a transaction completed via the Internet at a 3-D Secure capable merchant that attempted to authenticate the accountholder using 3-D Secure (examples: 3-D Secure includes Verified by Visa and Mastercard Identity Check.) Verified by Visa, Mastercard Identity Check, American Express SafeKey and Discover ProtectBuy transactions in the event of: * A non-participating issuer * A non-participating accountholder of a participating issuer * A participating issuer, but the authentication server is not available
7 (Chase) Channel Encrypted Transaction - Designates a transaction between an accountholder and a merchant completed via the Internet where the transaction includes the use of transaction encryption such as SSL (Secure Sockets Layer), but authentication was not performed. The accountholder payment data was protected with a form of Internet security, such as SSL, but authentication was not performed. For Discover, indicates an e-commerce Card Transaction with data protection in which ProtectBuy for Cardholder authentication was not used.
8 (Chase) Non-Secure Electronic Commerce Transaction - Designates a transaction between an accountholder and a merchant completed via the Internet where: * The transaction does not include the use of any transaction encryption such as SSL * Authentication is not performed * An accountholder certificate is not managed.
I (Chase) IVR Transaction (PINless Debit only) - Designates a transaction where the accountholder completes the sale via an interactive voice response (IVR) system.
R (Chase) Retail Transaction - Designates a transaction where the accountholder was present at a merchant location.
telephone (Vantiv) The transaction is for a single telephone order.
mailorder (Vantiv) The transaction is for a single mail order transaction.
<auto_assign_mandatory_supp_plans>
Allowable Values
Values Description
true Automatically assign mandatory Supplemental Plans. (default)
false Do not automatically assign mandatory Supplemental Plans.
<plan_directive>
Allowable Values
Values Description
1 Assign Plan as new Plan instance
2 Replace the Plan on the specified Plan instance
3 Update specified attributes on the given Plan instance
4 Cancel the specified Plan instance
<fulfillment_directive>
Allowable Values
Values Description
1 Complete fulfillment with immediate effect. This would be accomplished by specifying fulfillment date in past or today or without any fulfillment date. (default)
2 Complete fulfillment with effective date specified in future. A user must specify service_fulfillment_date with this directive.
3 Remove the already assigned fulfillment date.
<plan_unit_inst_field_val_directive>
Allowable Values
Values Description
1 Add Value
2 Replace Value
3 Remove Value
<proration_invoice_timing>
Allowable Values
Values Description
  Honor Proration Invoice Timing configuration saved with the Plan in the product catalog
0 Invoice immediately
1 Invoice on next anniversary date
<coupon_directive>
Allowable Values
Values Description
0 Remove coupon from Master Plan Instance
1 Add coupon to Master Plan Instance
<surcharge_directive>
Allowable Values
Values Description
0 Remove surcharge from Plan instance
1 Add surcharge to Plan instance
<plan_status_cd>
Allowable Values
Values Description
0 INACTIVE
1 ACTIVE
2 CANCELLATION PENDING
3 TERMINATION PENDING
31 INSTALLATION PENDING
32 REGISTERED PENDING ACTIVATION
41 ACTIVE TRIAL
61 ACTIVE NON-BILLABLE
-1 SUSPENDED
-2 CANCELLED
-3 TERMINATED
<status_until_alt_start_cd>
Allowable Values
Values Description
1 Active
2 Cancellation Pending
3 Termination Pending
31 Installation Pending
32 Registered Pending Activation
41 Active Trial
61 Active Non-billable
-1 Suspended
-2 Cancelled
-3 Terminated
<resp_level_cd>
Allowable Values
Values Description
1 Standard Self-Pay: default
2 Parent Pay: Usage accrues under self, invoices are generated per self's Plan rules BUT are presented for payment against parent account'
3 Parent Usage & Pay: Usage accrues under parent and applied only to parent's Plan rules and presented to parent for payment'
<plan_instance_field_directive>
Allowable Values
Values Description
1 Add name and value for a new Plan instance field (default).
2 Replace value of an existing Plan instance field.
3 Remove the value of an existing Plan instance field, note that if the Plan instance field is required based on the field definition, the Replace directive should be used.
4 Remove the name and value of an existing Plan instance field from the Plan instance.
<auto_offset_months_option>
Allowable Values
Values Description
1 sync to Master Plan recurring bill thru date
2 sync to old Supplemental Plan recurring bill thru date (only applies to Supplemental Plan)
<invoice_unbilled_usage>
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.
<force_master_bill_date_reset>
Allowable Values
Values Description
  If this value is left empty, the client-level setting (Sync_mstr_bill_dates_on_1st_supp) will take effect.
1 Do not reset Master Plan billing dates.
2 Reset Master Plan billing dates if Master Plan is "free", the account has no "billable" Supplemental Plans, and the newly-assigned Supplemental Plan is "billable.
3 Reset Master Plan billing dates if Master Plan is "free" and the account has no active Supplemental Plans.
<usage_accumulation_reset_months_renewal_option>
Allowable Values
Values Description
NULL or 1 Recurring / Auto Renew.(Default)
2 Single Use.
<usage_pooling>
Allowable Values
Values Description
true Usage pooling is enabled for this Plan instance.
false Usage pooling is not enabled for this Plan instance. (default)
<nso_bill_immediately>
Allowable Values
Values Description
0 Fulfill immediately. Bill on next anniversary. (default)
1 Fulfill immediately. Bill immediately.
2 Order Held.
3 Fulfill on fulfillment date. Bill on the next anniversary bill after the fulfillment date. Note that if the fulfilled date is in the past/current day, then the fulfillment will happen in API itself as in nso_bill_immediately = 0.
4 Fulfill on fulfillment date. Bill on the fulfillment date. Note that if the fulfilled date is in the past/current day, then the fulfillment and billing will happen in API itself as in nso_bill_immediately = 1.
5 Fulfill on fulfillment date. Bill on the next anniversary bill that bills arrears services through the fulfillment date. Note that if the fulfilled date is in the past/current day, then the fulfillment will happen in API itself as in nso_bill_immediately = 0.
<plan_instance_supp_field_update_only>
Allowable Values
Values Description
  This input will not allow Plan instance fields to be update for plans that are in a non-provisioned status
0 This input will not allow Plan instance fields to be update for plans that are in a non-provisioned status
1 This input will allow Plan instance fields to be update for plans that are in a non-provisioned status
<force_bill_date_reset>
Allowable Values
Values Description
  Reset the billing dates when the status changes from non-billable to billable depending on client parameter 'AUTO_RESET_MASTER_PLAN_BILLING_DATES_ON_NON_BILLABLE_TO_BILLABLE_MASTER_PLAN_STATUS_CHANGE' setting.
0 Do not reset the billing dates for this Plan.
1 Reset the billing anniversary date to coincide with the status change date.
2 Reset the billing anniversary date to coincide with the current anniversary date.
<billing_group_directive>
Allowable Values
Values Description
1 Create new billing group
2 Update billing group
<notify_method>
Allowable Values
Values Description
0 None
1 HTML Email
2 Text Email
3 Text Email w/link to HTML
4 Data export
5 Printable (no Email) w/Surcharge
6 Printable & Text Email
7 Printable & HTML Email w/Surcharge
8 Printable (no Email)
9 PDF (Printing required, no Email)
10 PDF (delivered by Email)
11 PDF (Printing req & Email)w/surcharge
12 PDF (Printing req, no Email)w/surcharge
13 XML Master File
14 PDF Master File
15 XML Master File and HTML Email
16 XML Master File and Text Email
17 PDF Master File and HTML Email
<payment_option>
Allowable Values
Values Description
Methods Methods
Terms Terms
<bg_list_start_master_file>
Allowable Values
Values Description
0 0
1 When value=1, account is listed at the top of the master file when generated.
<collections_grp_directive>
Allowable Values
Values Description
1 Assign the collection group to the billing group.
2 Remove the collection group from the billing group.
<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. Applicable when plan_directive = 1, 2, 3, 4.
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. Applicable when plan_directive = 1, 2, 3, 4.
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. Applicable when plan_directive = 1, 2, 3, 4.
4 Perform the requested Plan change immediately, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing PRORATION. Applicable when plan_directive = 1, 2, 3, 4.
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.Applicable when plan_directive = 1, 2, 3.
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. Applicable when plan_directive = 2, 3, 4.
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. Applicable when plan_directive = 1, 2, 3, 4.
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. Applicable when plan_directive = 1, 2, 3, 4.
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. Applicable when plan_directive = 1, 2, 3, 4.
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. Applicable when plan_directive = 1, 2, 3.
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. Applicable when plan_directive = 2, 3, 4.
<invoicing_option>
Allowable Values
Values Description
1 Perform full invoicing
2 Perform Prorated invoicing
3 Use client default configuration setting
4 None
<payment_method_type>
Allowable Values
Values Description
-1 External Payment
0 Other
1 Credit card
2 Electronic Check (ACH)
3 Pre-paid
4 Net terms 30
5 Net terms 10
6 Net terms 15
7 Net terms 60
8 Click&Buy
9 Net Terms 0
10 PayByCash
11 PayPal Express Checkout
12 Net Terms 45
13 Tokenized Credit Card
14 Purchase Power
15 Net Terms 35
16 Net Terms 75
17 Net Terms 90
18 Net Terms 120
19 Net Terms 25
26 Direct Debit
37 Tokenized Direct Debit
48 Tokenized ACH
<bank_acct_type>
Allowable Values
Values Description
savings savings
checking checking
business business
<dunning_group_directive>
Allowable Values
Values Description
1 Create new dunning group
2 Update dunning group
<auto_collect_on_plan_chng>
Allowable Values
Values Description
  Collect based on the value in the client parameter "auto collect on Master Plan change" and / or "auto collect on Supplemental Plan change". If both a master and Supplemental Plan are updated and invoiced in the same call, the Master Plan setting will override the Supplemental Plan setting.
0 Do not collect automatically when the Plan in changed.
1 Collect automatically when the Plan is changed.
<rollback_plan_chng_collect_fail>
Allowable Values
Values Description
1 Roll back Plan change when collection fails (default).
0 Do not roll back the Plan change when the collection fails.
<auto_send_stmt_on_plan_chng>
Allowable Values
Values Description
  Statement will be sent based on the value in the client parameter "send statement on Master Plan change" and / or "send statement on Supplemental Plan change". If both a master and Supplemental Plan are updated and invoiced in the same call, the Master Plan setting will override the Supplemental Plan setting.
0 Do not send a statement automatically when the Plan in changed.
1 Send a statment automatically when the Plan is changed.
<do_write>
Allowable Values
Values Description
true true
false false
<list_start_master_file>
Allowable Values
Values Description
0 0
1 When value=1, account is listed at the top of the master file when generated.
<combine_invoices>
Allowable Values
Values Description
1 Combine Invoices (long cycle)
2 Do Not Combine Invoices (short cycle)
3 Use client default configuration setting
<remove_pi_custom_rates>
Allowable Values
Values Description
true Remove the custom rates and use the default rates of the new rate schedule that you assigned.
false (default) Keep the custom rates currently assigned to the Plan instance.
<config_dunning_late_fee_option>
Allowable Values
Values Description
1 Use dunning process configuration settings (default).
0 Do not use dunning process configuration/do not charge late fee.
<config_dunning_email_option>
Allowable Values
Values Description
1 Use dunning process configuration settings (default).
0 Do not use dunning process configuration/do not send email notification.
<recurring_processing_model_ind>
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>
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.
<force_currency_change>
Allowable Values
Values Description
false (Default) When the Plan being updated has a rate schedule with a different currency or the supplied alternate rate schedule has rates defined in different currency, a 'false' value will not allow the currency change.
true When the Plan being updated has a rate schedule with a different currency or the supplied alternate rate schedule has rates defined in different currency, a 'true' value will allow the currency change provided that there are no transactions (or only $0 transaction present) for that account and the new plan/alt rate schedule has the rates defined in the target currency.

Output Fields

Field Name: Notes:

<tax_details> (array)

  • <unrounded_tax_amt>
  • <carryover_from_prev_amt>
  • <before_round_adjusted_tax_amt>
  • <carryover_from_current_amt>

Assuming that the client setting Aria Internal Tax Rounding Method is set to "Per invoice."
<plan_operation>
Allowable Values
Values Description
1 Plan assigned and Plan instance created
2 Plan replaced on existing Plan instance
3 Plan instance updated
4 Plan cancelled
<line_type>
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
  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Page type
    Topic
  2. Tags
    This page has no tags.