Home > Aria Crescendo Documentation > Aria Crescendo core api > assign_acct_plan_m

assign_acct_plan_m

Assigns a new master or Supplemental Plan to the specified account.

When you assign a newPlanto an account, you can assign the following:

  • Billing group
  • Notification method and template
  • Payment methods
  • Contact information for billing, statements, and payment methods
  • Dunning information
  • Start date and proration options
  • Balance forward
  • Relationship to other Plans (parent, child, etc.)
  • Rate schedules
  • Coupons, promotion codes and surcharges
  • NSO and SKU information

Note: 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 is determined based on your setting for the parameter Override Bill Thru Date SuppPlanBehavior.

To see a description of the parameter, click Configuration > Billing > Invoice Settings.

For a list of error messages generated by this API, see assign_acct_plan_m Error Messages.

Input Arguments

Req Field Name Field Type Max Length Description
required-icon.png client_no long 22 Aria-assigned unique identifier indicating the Aria client providing service to this account.
required-icon.png auth_key string 32 Aria-assigned unique key to be passed with each method call for authenticating the validity of the requestor.
required-icon.png acct_no long 22 Aria-assigned account identifier. This value is unique across all Aria-managed accounts.
  OR      
  client_acct_id string 50 Client-defined account identifier.
required-icon.png new_plan_no long 22 The unique identifier of the newPlanreplacing the existingPlanon the instance.
  OR      
  new_client_plan_id string 100 The client-defined identifier of the newPlanreplacing the existingPlanon the instance.
  client_plan_instance_id string 100 Unique Master Plan Instance client-defined identifier
  existing_billing_group_no long 22 Billing group number
  OR      
  existing_client_billing_group_id string 100 Client-defined unique identifier for billing group
  billing_group_name string 100 Billing Group name
  billing_group_description string 1000 Billing group description
  client_def_billing_group_id string 100 Client-defined unique identifier for billing group
  notify_method long 2 How the client communicates with the account holder. If a notification method is not provided, this value defaults to "1" (HTML email).  

Allowable values for notify_method:

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
  notification_template_group_id long 22 Notify template No. Aria-assigned unique identifier for the notification template group to be associated with the account.
 

client_notification_template_group_id

 string 50

Client-defined unique identifier for the notification template group to be associated with the account.
  statement_template long 22 Statement template No.
  credit_note_template long 22 Credit note template No.
  existing_primary_payment_method_no long 22 Primary payment method ID (Note: The same pay method sequence number cannot be used for the primary and secondary payment method.)
  existing_client_primary_payment_method_id string 100 Client-defined unique identifier of the primary payment method (Note: The same pay method sequence number cannot be used for the primary and secondary payment method.)
  existing_backup_payment_method_no long 22 Backup payment method ID (Note: The same pay method sequence number cannot be used for the primary and secondary payment method.)
  existing_client_backup_payment_method_id string 100 Client-defined unique identifier of the backup payment method (Note: The same pay method sequence number cannot be used for the primary and secondary payment method.)
  stmt_first_name string 300 Statement contact first name
  stmt_mi string 2 The Middle Initial of the statement contact.
  stmt_last_name string 300 Statement contact Last name
  stmt_company_name string 100 Company name of the statement contact
  stmt_address1 string 300 First address line of the statement contact
  stmt_address2 string 300 Second address line of the statement contact. If you want to delete existing data in this field, leaving it blank, you must enter a '~' in this field.
  stmt_address3 string 300 Third address line of the statement contact
  stmt_city string 300 City of the statement contact
  stmt_locality string 300 Use this field instead of the state_prov field to designate the state, province or other local designation as appropriate for addresses in all countries other than the United States, Australia, and Canada. This field is ignored for all United States, Australia and Canada addresses.
  stmt_state_prov string 10 State or Province of the billing contact. The official postal-service codes for all United States, Australia and Canada states, provinces, and territories. This field does not support states, provinces or territories from other countries. Use the locality field for other countries.
  stmt_country string 25 Country of the contact. The ISO-compliant 2-character country code abbreviation in uppercase.
  stmt_postal_cd string 15 Postal/Zip code for the statement contact address.
  stmt_phone string 25 The phone number of the statement contact
  stmt_phone_ext string 10 The extension for the statement contact phone
  stmt_cell_phone string 20 The contact cell phone of the statement contact.
  stmt_work_phone string 25 Work phone number of the statement contact.
  stmt_work_phone_ext string 10 The extension for the statement contact work phone
  stmt_fax string 25 The fax number for the statement contact.
  stmt_email string 320 Email of the statement contact
  stmt_birthdate string 10 The birthdate, in yyyy-mm-dd format, of the statement contact.
  bill_first_name string 300 First name of the billing contact.
  bill_middle_initial string 2 Middle initial of the billing contact.
  bill_last_name string 300 Last name of the billing contact.
  bill_company_name string 100 Company name of the billing contact.
  bill_address1 string 300 First address line of the billing contact.
  bill_address2 string 300 Second address line of the billing contact. If you want to delete existing data in this field, leaving it blank, you must enter a '~' in this field.
  bill_address3 string 300 The third line of the billing address.
  bill_city string 300 City of the billing contact.
  bill_locality string 300 Use this field instead of the state_prov field to designate the state, province or other local designation as appropriate for addresses in all countries other than the United States, Australia, and Canada. This field is ignored for all United States, Australia and Canada addresses.
  bill_state_prov string 10 State or Province of the billing contact. The official postal-service codes for all United States, Australia and Canada states, provinces, and territories. This field does not support states, provinces or territories from other countries. Use the locality field for other countries.
  bill_country string 25 Country of the billing contact. The ISO-compliant 2-character country code abbreviation in uppercase.
  bill_postal_cd string 15 Postal code for the billing contact.
  bill_phone string 25 Phone number of the billing contact.
  bill_phone_ext string 10 Phone extension of the billing contact.
  bill_cell_phone string 20 Cell phone number of the billing contact.
  bill_work_phone string 25 Work phone number of the billing contact.
  bill_work_phone_ext string 10 This is the work phone extension for the billing contact work phone.
  bill_fax string 25 Fax number of the billing contact.
  bill_email string 320 Email of the billing contact.
  bill_birthdate string 10 Birthdate of the billing contact.
  primary_pay_method_name string 100 Payment method name.
  primary_pay_method_cdid string 100 Client-defined unique identifier for the payment method.
  primary_pay_method_description string 1000 Payment method description
  primary_pay_method_type long 8 This is the method_id corresponding to a payment method such as credit card, Electronic Check, Pre-Paid, Net Terms, etc.  

Allowable values for primary_pay_method_type:

Values Description
-1 External Payment
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
20 NETS
26 Direct Debit
37 Tokenized Direct Debit
48 Tokenized ACH
  cc_number string 20 Credit card number.
  cc_expire_mm long 2 Expiration month for the credit card payment instrument.
  cc_expire_yyyy long 4 Expiration year for the credit card payment instrument.
  bank_acct_no string 19 The bank account number (the <bank_acct_no>, <bank_routing_no> or <bill_agreement_id> is needed for the Tokenized ACH payment method - 48).
  bank_routing_no string 9 The ABA routing number for the bank holding bank_acct_no (the <bank_acct_no>, <bank_routing_no> or <bill_agreement_id> is needed for the Tokenized ACH payment method - 48).
  cvv string 6 Card Verification Value, used to help verify a transaction is being requested by the card holder since this value is physically printed on the credit card.
  track_data1 string 300 Raw "track 1" data from a swiped credit card used in a card-present transaction to initiate this request
  track_data2 string 300 Raw "track 2" data from a swiped credit card used in a card-present transaction to initiate this request
  bill_agreement_id string 32 Unique ID of the bill agreement (also referred to as a token). The <bank_acct_no>, <bank_routing_no> or <bill_agreement_id> is needed for the Tokenized ACH payment method - 48.
  iban string 50 International Bank Account Number(IBAN). Used for the Direct Debit payment method. It consists of 16 to 34 alphanumeric characters. Only hyphen and space are allowed to format the IBAN.
  bank_check_digit long 2 Bank check digits enable a sanity check of the bank account number to confirm its integrity before submitting a transaction. Used for the Direct Debit payment method.
  bank_swift_cd string 15 SWIFT code is a standard format of Bank Identifier Codes (BIC). It is used for the Direct Debit payment method. It consists of 8 or 11 alphanumeric characters. Only hyphen and space are allowed to format the SWIFT code. It is required for IBAN.
  bank_country_cd string 2 Country of the bank. The ISO-compliant 2-character country code abbreviation in uppercase. Used for the Direct Debit payment method. It is required for IBAN and BBAN.
  mandate_id string 35 Used for the Direct Debit payment method. A mandate is signed by the debtor to authorize the creditor to collect a payment and to instruct the bank of the debtor to pay those collections.
  bank_id_cd string 15 Up to 10 digit numeric bank identifier code. Used for the Direct Debit payment method. Only hyphen and space are allowed to format the bank ID code. It is required for BBAN.
  bank_branch_cd string 15 Up to 10 digit numeric bank branch code. Used for the Direct Debit payment method. Only hyphen and space are allowed to format the bank branch code.
  bank_name string 100 Bank name for the account payment method. 
  bank_city string 100 Bank city for the account payment method.
  existing_dunning_group_no long 22 The dunning group number mapped against each Master Plan.

Note: It is now required that dunning groups are associated with parent-pay Master Plan Instances, so even if a dunning group is not specified by the client upon MPI assignment, an empty dunning group (i.e., without any values in the attributes) will be created and assigned to that MPI automatically, without issuing an error or warning.
  OR      
  existing_client_def_dunning_group_id string 100 The client-defined dunning group ID mapped against each Master Plan.

Note: It is now required that dunning groups are associated with parent-pay Master Plan Instances, so even if a dunning group is not specified by the client upon MPI assignment, an empty dunning group (i.e., without any values in the attributes) will be created and assigned to that MPI automatically, without issuing an error or warning.
  dunning_group_name string 100 Name of the dunning group.
  dunning_group_description string 1000 Description of the dunning group.
  client_dunning_group_id string 100 Client-defined dunning group identifier.
  dunning_process_no long 22 Dunning process code.
  OR      
  client_dunning_process_id string 100 Client-defined dunning process identifier.
  alt_start_date string 10 Alternative start date, in yyyy-mm-dd format, for the Master Plan Instance being assigned on the account. This date can be used to delay providing services to the account holder (for example: until they have been email validated), and must be within one billing interval of thePlanbeing assigned.
  status_until_alt_start long 8 Status of the Master Plan Instance prior to alt_start_date or alt_bill_day. If the alt_start_date or alt_bill_day field is used, this field is required and defaults to 0 (inactive) if no value is provided. If an alternate starting date or alternate bill day is provided, the Master Plan Instance remains in this status until its start date arrives. This only applies if a prorated invoice is not created. If a prorated invoice is created, this field is ignored.  

Allowable values for status_until_alt_start:

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
  alt_bill_day long 2 Number specifying a day of the month to use as an alternate bill day. You can enter a bill date other than the anniversary date in this field. The invoice_mode must be set to 0 or must be blank to enter a date in this field, it cannot be set to 1.
  invoicing_option long 1 Indicator for performing full invoicing, and Perform Prorated Invoicing or client-defined on this account as part of this call.  

Allowable values for invoicing_option:

Values Description
1 Perform full invoicing
2 Perform prorated invoicing
3 use client default
4 None
  retroactive_start_date string 10 Date, in yyyy-mm-dd format, to set for retroactive start.
  override_bill_thru_date string 10 Applicable only for Master Plan assignment. When provided, this date will be used as the bill thru date for the Master Plan Instance. The alt_start_date or retroactive_start_date input will be honored with override_bill_thru_date, but invoicing_option must be set to Perform Prorated Invoicing. The override_dates_mp_instance_no or override_dates_client_mp_instance_id parameters take precedence over this input parameter, and if provided together the override_bill_thru_date input will be ignored. The date provided must be in the future, must be after the alt_start_date (if provided), and cannot exceed one recurring billing interval. This parameter cannot be used with alt_bill_day or status_until_alt_start (defaults to Inactive). A prorated invoice will be generated for recurring services from the effective start date of thePlaninstance through the override_bill_thru_date provided. If thePlanbeing assigned has no usage services, the next_bill_date (aka anniversary date) will be the override_bill_thru_date + 1 day. If thePlanhas usage services, then the next_bill_date will be calculated based on the usage interval to be the earliest date in the future that will ensure usage and recurring services will be invoiced together on the override_bill_thru_date + 1 day.
  override_dates_mp_instance_no long 22 Applicable only for Master Plan assignment. When provided, the billing dates for the new Master Plan being assigned will be aligned with the billing dates of the existing Master Plan Instance specified (honoring the bill day of the existing Master Plan Instance). The alt_start_date or retroactive_start_date input will be honored with the override_dates_mp_instance_no or the override_dates_client_mp_instance_id, but invoicing_option must be set to Perform Prorated Invoicing. These parameters take precedence over the override_bill_thru_date parameter, and cannot be used with alt_bill_day or status_until_alt_start (defaults to Inactive). If the recurring interval of the new Master Plan Instance will be the same as or longer than the existing Master Plan Instance, a prorated invoice for the Master Plan being assigned will be generated for recurring services from the effective start date of thePlaninstance through the bill_thru_date of the existing Master Plan Instance. If the recurring interval of the new Master Plan Instance will be shorter than the existing Master Plan Instance, the bill_thru_date for the new Master Plan Instance will be calculated based on its recurring interval to be the earliest date in the future that will ensure the recurring services for both Master Plan Instances will be invoiced together on the existing Master Plan Instance's bill_thru_date + 1 day. In the above scenarios, if the new Master Plan Instance has no usage services, the next_bill_date (aka anniversary date) will be the bill_thru_date + 1 day. If the new Master Plan Instance has usage services, then the next_bill_date will be calculated based on the usage interval to be the earliest date in the future that will ensure usage and recurring services will be invoiced together on the bill_thru_date + 1 day.
  OR      
  override_dates_client_mp_instance_id string 100 Applicable only for Master Plan assignment. When provided, the billing dates for the new Master Plan being assigned will be aligned with the billing dates of the existing Master Plan Instance specified (honoring the bill day of the existing Master Plan Instance). The alt_start_date or retroactive_start_date input will be honored with the override_dates_mp_instance_no or the override_dates_client_mp_instance_id, but invoicing_option must be set to Perform Prorated Invoicing. These parameters take precedence over the override_bill_thru_date parameter, and cannot be used with alt_bill_day or status_until_alt_start (defaults to Inactive). If the recurring interval of the new Master Plan Instance will be the same as or longer than the existing Master Plan Instance, a prorated invoice for the Master Plan being assigned will be generated for recurring services from the effective start date of thePlaninstance through the bill_thru_date of the existing Master Plan Instance. If the recurring interval of the new Master Plan Instance will be shorter than the existing Master Plan Instance, the bill_thru_date for the new Master Plan Instance will be calculated based on its recurring interval to be the earliest date in the future that will ensure the recurring services for both Master Plan Instances will be invoiced together on the existing Master Plan Instance's bill_thru_date + 1 day. In the above scenarios, if the new Master Plan Instance has no usage services, the next_bill_date (aka anniversary date) will be the bill_thru_date + 1 day. If the new Master Plan Instance has usage services, then the next_bill_date will be calculated based on the usage interval to be the earliest date in the future that will ensure usage and recurring services will be invoiced together on the bill_thru_date + 1 day.
  balance_forward double 12 balance forward
  resp_level_cd long 1

The responsibility level code. These are values 1 through 3 as described in the legend for this argument.  

 

To specify the responsible Master Plan Instance for the assigned Plan, pass in a <resp_master_plan_instance_no> and/or <resp_client_master_plan_instance_id> as described below.

Please see Parent-child Account Best Practices for more information.

Allowable values for resp_level_cd:

Values Description
1 Standard Self-Pay: default
2 Parent Pay: Usage accrues under self, invoices are generated per self'sPlanrules BUT are presented for payment against parent account'
3 Parent Usage & Pay: Usage accrues under parent and applied only to parent'sPlanrules and presented to parent for payment'
  parent_acct_master_plan_inst_id (DEPRECATED) long 22 Identifier for a parent account Master Plan. Required if resp_level_cd is 2 or 3.
  parent_plan_instance_no long 22 Unique identifier of aPlanin thePlaninstance hierarchy under which the newPlanwill be assigned.
  OR      
  client_parent_plan_instance_id string 100 Unique Client-defined identifier of aPlanin thePlaninstance hierarchy under which the newPlanwill be assigned.
  alt_rate_schedule_no long 22 Alternative Rate Schedule Number. The alt_rate_schedule_no is the unique identifier for an alternative rate schedule that can be assigned to the account holder in place of the default rate schedule. This is often done by CSRs to provide special compensation or discounts as incentives to account holders.
  OR      
  client_alt_rate_schedule_id string 100 Client-defined alternate rate schedule identifier to assign (if any). If none is specified, the default rate schedule number will be used.
  plan_units double   The units of thePlanadded at this change
  coupon_codes string array 30 The coupon codes to assign to this Master Plan Instance, if any
  promo_cd string 30 This is the code provided the client and used by the account holder during registration or when executing a transaction. A promotion generally provides access to a custom set of reduced-rate Plans.
Start of mpi_surcharges array
  mpi_surcharges array   Surcharge for Master Plan Instance
  Field Name Field Type Max Length Description
  brd_arrow.gifmpi_surcharge_no long 22 The surcharge number to assign to the Master Plan. Required when assigning a surcharge to a Master Plan.
  brd_arrow.gifmpi_rate_schedule_no long 22  
End of mpi_surcharges array
 
  plan_status long 2 Updates thePlanstatus for thePlaninstance. 

Allowable values for plan_status:

Values Description
1 Active
2 Pending Cancellation
3 Pending Termination
31 Pending Installation
32 Pending Activation
41 Trial
61 Active Non-billable
0 Inactive
-1 Suspended
-2 Cancelled
-3 Terminated
  plan_instance_description string 1000 Updated the description for thePlaninstance.
Start of plan_instance_fields array
  plan_instance_fields array    
  Field Name Field Type Max Length Description
  brd_arrow.gifplan_instance_field_name string 100 Required based on the definition of eachPlaninstance field associated with the new Plan.
  brd_arrow.gifplan_instance_field_value string 100 Required based on the definition of eachPlaninstance field associated with the new Plan.
End of plan_instance_fields array
 
  assignment_directive long 8 The rule to be applied to this assignment request, governing the proration rule is applied. Default behavior is to make thePlanchange (assign/deassign aPlanto an account, change units on an existing Plan, etc.) immediately based on client-defined default proration rule, resulting in appropriate prorated charge and credit. This field is only honored for a Supplemental Plan, and not for Master Plans.  

Allowable values for assignment_directive:

Values Description
1 (Default) Perform the requestedPlanchange on the account's next scheduled billing anniversary date. The account does receive service under thisPlan(forPlanassignments) or have it removed (for de-assignments) until that date. If aPlanis being assigned, initial billing for a full period of the givenPlanis 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 requestedPlanchange immediately, honoring the client's pre-configured universal rule for performing or not performing proration as a result of a mid-billing-periodPlanassignment or de-assignment. No new recurring charges or credits are generated when no proration occurs.
3 Perform the requestedPlanchange 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 requestedPlanchange immediately, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing PRORATION.
5 Perform the requestedPlanchange 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.
7 Perform the requestedPlanchange 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-periodPlanassignment or de-assignment. No new recurring charges or credits are generated when no proration occurs.
8 Perform the requestedPlanchange 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 requestedPlanchange 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 requestedPlanchange 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.
  comments string 500 Additional explanatory text relating to this API call.
  do_write string 5 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,Planassignments, 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 for do_write:

Values Description
true true
false false
  client_receipt_id string 50 Client-defined unique identifier used to track related system actions
  offset_months long 4

ForPlanrecurring intervals of longer than one month, the number of months to offset proration and first bill date.

Note: This API does not support the use of the <offset_months> input with an anniversary <assignment_directive>. Instead, you can use the <offset_interval> field with an anniversary <assignment_directive> to delay the addition of aPlanwith a daily, weekly, or any other billing interval.
  alt_proration_start_date string 10

The date, in yyyy-mm-dd format, from which the proration calculations begin. If this field is NULL, then the proration calculations begin from the current date. This date cannot be before the beginning of the current billing period.

Notes:

  1. 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.
  2. 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.
  auto_offset_months_option long 1 Automatically set the offset for the billing anniversary month.  

Allowable values for auto_offset_months_option:

Values Description
1 sync to Master Plan recurring bill thru date
  alt_client_acct_group_id string 100 One-time collections account group to use for this specific call. Default collections group on the account is not changed.
  usage_accumulation_reset_months long 4 The number of reset months for each Plan.
  usage_pooling string 5 Indicates whether usage pooling is enabled for thisPlaninstance. Allowable values are 'true' and 'false'.  

Allowable values for usage_pooling:

Values Description
true Usage pooling is enabled for thisPlaninstance.
false Usage pooling is not enabled for thisPlaninstance. (default)
  usage_threshold_applicability string 2 Usage tracking options on the Plans in the account  

Allowable values for usage_threshold_applicability:

Values Description
UT Usage Type
UP Usage Pool
Start of custom_rates array
  custom_rates array   An array of custom rates for the specified account number
  Field Name Field Type Max Length Description
  brd_arrow.gifcustom_rate_service_no long 22 The unique identifier for the service no, relative to the value provided in corresponding "custom_rate_plan_no", to which this custom rate is to be applied for this account.
  OR      
  brd_arrow.gifcustom_rate_client_service_id string 100 The unique identifier by client the service ID to determine which custom rate is to be applied for this account.
  brd_arrow.gifcustom_rate_seq_no long 22 The rate tier number, relative to the values provided in corresponding "custom_rate_plan_no" and "custom_rate_service_no", to which this custom rate is to be applied for this account.
  brd_arrow.gifcustom_rate_from_unit long 22 The unit starting point, relative to the values provided in corresponding "custom_rate_plan_no", "custom_rate_service_no" and "custom_rate_seq_no", to which this custom rate is to be applied for this account.
  brd_arrow.gifcustom_rate_to_unit long 22 The unit ending point, relative to the values provided in corresponding "custom_rate_plan_no", "custom_rate_service_no" and "custom_rate_seq_no", to which this custom rate is to be applied for this account.
  brd_arrow.gifcustom_rate_per_unit double 22 The custom rate per unit, relative to the values provided in corresponding "custom_rate_plan_no", "custom_rate_service_no" and "custom_rate_seq_no", to be applied for this account.
End of custom_rates array
 
  effective_date string 10 If the assignment directive is for a future date assignment, this is the date, in yyyy-mm-dd format, on which thePlanchange will be executed. If this field is NULL, then thePlanchange will not happen until it is manually executed or until the effective_date is updated.
  offset_interval long 4 If assigning a change on an anniversary day, the number of billing periods by which to delay that change. If the newPlanis different from the old Plan, and this value is greater than 0, then the billing date continues to be the anniversary date.
  force_supp_bill_date_reset long 1 Deprecated(Deprecated) This input is not operational. Use 'force_master_bill_date_reset' to perform this input's activity.
  nso_bill_immediately long 1 Indicates whether to bill the NSO items immediately or if not set bill on next billing anniversary date.  

Allowable values for nso_bill_immediately:

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.
Start of nso_item_list array
  nso_item_list array   Non-Subscription Offerings that are purchased with the Plan
  Field Name Field Type Max Length Description
  brd_arrow.gifclient_sku string 100 Client SKU of the NSO/Inventory item.
  brd_arrow.gifitem_units long 22 NSO quantity that is purchased along with Plan
  brd_arrow.gifitem_svc_location_no long 22 The Aria-assigned unique identifier for the origin location for the item (NSO) being purchased. Depending on taxation configuration, this address may be used for tax calculations. If both svc_location_no and client_svc_location_id are provided, svc_location_no will take precedence.
  brd_arrow.gifclient_item_svc_location_id string 100 The client-defined unique identifier for the origin location for the item (NSO) being purchased. Depending on taxation configuration, this address may be used for tax calculations. If both svc_location_no and client_svc_location_id are provided, svc_location_no will take precedence.
  brd_arrow.gifitem_dest_contact_no long 22 The Aria-assigned unique identifier for the destination contact for the item (NSO) being purchased. Depending on taxation configuration, this address may be used for tax calculations.
End of nso_item_list array
 
  proration_invoice_timing long 1 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 thePlanin the product catalog.  

Allowable values for proration_invoice_timing:

Values Description
Null(default) Honor Proration Invoice Timing configuration saved with thePlanin 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.
  po_num string 100 Purchase order number assigned to thePlaninstance.
  nso_po_num string 100 Purchase order number assigned to the one-time order.
  cc_id long 2 A numeric code indicating the type of credit card.  

Allowable values for cc_id:

Values Description
1 Visa
2 MasterCard
3 American Express
4 Discover
5 Diners Club/Carte Blanche
6 Maestro
7 JCB
8 Laser
9 Dankoort
  bill_contact_no long 22 The Aria-assigned unique identifier for the contact on this account to be used as the billing contact for the payment method. If bill_contact_no is included in the API request, all other billing contact parameters are ignored.
  stmt_contact_no long 22 The Aria-assigned unique identifier for the statement contact associated with a billing group on the account.
Start of plan_update_services array
  plan_update_services array   List of services associated with thePlanbeing assigned or updated on the account.
  Field Name Field Type Max Length Description
  brd_arrow.gifservice_no long 22 The Aria-assigned unique identifier for the service associated with thePlaninstance. Either this field or client_service_id is required to mapPlanservices to thePlaninstance.
  OR      
  brd_arrow.gifclient_service_id string 100 The client-defined identifier for the service associated with thePlaninstance.
  brd_arrow.gifsvc_location_no long 22 The Aria-assigned unique identifier for the origin location for the specified service associated with the Plan. Depending on taxation configuration, this address may be used for tax calculations. If both svc_location_no and client_svc_location_id are provided, svc_location_no will take precedence.
  brd_arrow.gifclient_svc_location_id string 100 The client-defined unique identifier for the origin location for the service associated with the Plan. Depending on taxation configuration, this address may be used for tax calculations. If both svc_location_no and client_svc_location_id are provided, svc_location_no will take precedence.
  brd_arrow.gifdest_contact_no long 22 The Aria-assigned unique identifier for the destination contact for the specified service associated with the Plan. Depending on taxation configuration, this address may be used for tax calculations.
End of plan_update_services array
 
  combine_invoices long 1 Indicator for combining invoices when retroactive start dates, negative bill lag days, orPlanchanges just prior to the next billing date would otherwise have generated multiple invoices. The allowable values are 1, 2, or 3.  

Allowable values for combine_invoices:

Values Description
1 Combine Invoices (long cycle)
2 Do Not Combine Invoices (short cycle)
3 Use client default configuration setting
  credit_memo_template long 22 Credit template No.
  rebill_template long 22 Rebill template No.
  force_master_bill_date_reset long 1 Overrides the "Sync_mstr_bill_dates_on_1st_supp" client-level setting that determines whether or not no-charge Master Plan billing dates should be reset when assigning a new Supplemental Plan or when the Supplemental Plan instance status is updated to a billable status. If this value is left empty, the client-level setting will take effect.  

Allowable values for force_master_bill_date_reset:

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.
  alt_caller_id string 30 Person or process that submitted the API call. This can be someone's user ID, or the name of an application.
Start of optional_transaction_qualifiers
  optional_transaction_qualifiers array   Array of additional values you can associate with this API call.
  Field Name Field Type Max Length Description
  brd_arrow.gif qualifier_name string 100 Name of the field you want to associate with this API call.
  brd_arrow.gif qualifier_value string 100 Corresponding value of the field you want to associate with this API call.
End of optional_transaction_qualifiers
 
Start of collection_group_bg_row array
  collection_group_bg_row array  

Array of collection groups that should be assigned to the specified billing groups.

For cost savings or for other reasons, you may choose to have payments made with a particular payment method (associated with a billing group) processed by a specific payment gateway. To do so, you can assign a collection group to a billing group by passing values into the collection_group_bg_row array.

Notes:

  • 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.
  • Only one collection group can be assigned to each billing group.
  • Aria now will allow 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.
  Field Name Field Type Max Length Description
 

brd_arrow.gif collections_group_bg_no

 

 

OR

 

 

brd_arrow.gifclient_collections_group_bg_id

long

 

 

 

 

 

string

22

 

 

 

 

 

100

Aria-assigned identifier of the collection group to assign to the specified billing group.

 

 

 


Client-defined identifier of the collection group to assign to the specified billing group.
End of collection_group_bg_row array
 
  application_id string 300 The application identifier in which the API is being used in. (Example: “Sales Force”)
  application_date string 300 The application date/timestamp, ie. 01/01/2014 10:00:00 to track when the application called the API.
  recurring_processing_model_ind long 1 Defines a recurring payment type for Credit Card and Tokenized Credit Cards. 

Allowable values for recurring_processing_model_ind:

Values Description
0 Cardholder-Initiated Transaction – Credentials on File: a credit card transaction initiated by the cardholder for a new order or aPlanupgrade 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 orPlanupgrade) that uses a credit card that is currently stored in Aria.
  usage_accumulation_reset_months_renewal_option long 1 Determines whether the usage accumulation reset months will automatically reset to same value at the end of the current period or will expire at end of current period.  

Allowable values for usage_accumulation_reset_months_ renewal_option:

Values Description
NULL or 1 Recurring / Auto Renew.(Default)
2 Single Use.
  bill_lag_days long 10

Bill lag days are the number of days prior to (negative) or after (positive) an account billing date at which an invoice should be generated for your specified master plan instance. 

Negative bill lag days are typically used for subscription-based services (often subscription-based services paid using net terms), for which you would like to send out invoices to your customers well in advance of the real invoice date. This gives your customers time to receive a paper or email invoice (statement) and send a payment before the actual invoice date.

Positive bill lag days typically apply to usage-based services. 

Examples:

  • If you want an invoice to be generated 14 days before the billing date, pass -14 into this field.
  • If you want an invoice to be generated 10 days after the billing date, pass 10 into this field.

By default, bill lag days are restricted to +/- the (minimum number of days in a recurring billing period – 1 day). However, if your  Allow Negative Bill Lag Days to Extend Beyond One Bill Cycle parameter is set to True (in the Aria application under Configuration > Billing> Invoice Settings), then the negative value can go beyond a single billing period.

Bill lag days can be removed via APIs update_acct_plan_m, replace_acct_plan_m, update_acct_plan_multi_m and update_acct_complete_m). To remove the MPI bill lag days, pass the standard "numeric erase" indicator of a tilde (~) for <bill_lag_days> input.

Note:

  • Although ‘-999’ happens to be a valid bill_lag_days value when the your parameter “_Allow Negative Bill Lag Days to Extend Beyond One Bill Cycle_” is “True”, it is obviously not practical as a real value on the APIs as there are not many plausible scenarios where a customer would be invoiced that far in advance.

Aria will set the bill lag days for plans using this order of precedence:

  1. Master plan instance (for a given account)
  2. Collection group setting
  3. Payment terms/payment method setting
  4. Client setting (Configuration > Billing > Bill Lag Days)

Notes:

  • You cannot pass a value into the <bill_lag_days> field by itself. You must also pass in a value to update the plan units, plan status, and/or alternate rate schedule.
  • <bill_lag_days> cannot be passed in as part of an API call used to schedule changes that will take place on a customer's anniversary date. You must set the <bill_lag_days> to go into effect on a date other than the anniversary date.

    Example: If you have an MPI replacement scheduled for a customer's anniversary date, you should not set <bill_lag_days> in the API used for the MPI replacement. If you do, Aria will ignore the <bill_lag_days>.
Start of proc_field_override array
  brd_arrow.gif proc_field_override array  

Your chosen data to send to your payment gateway passed as an array of proc_field_name/proc_field_value key-value pairs.

The allowable field(s) and values for the key-value pairs are listed below.
  Field Name Field Type Max Length Description
    brd_arrow.gifbrd_arrow.gif transaction_type string 2

If you use Chase Paymentech or Vantiv, this field allows you to tell that payment gateway which transaction type is involved (examples: single or recurring transaction) when you process a customer's  payment information.

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

 

Notes:

  • 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 for transaction_type:

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.
End of proc_field_override array
 

resp_master_plan_instance_no

 

 

 

OR

 

resp_client_master_plan_instance_id

long

 

 

 

 

 

string

22

 

 

 

 

 

100

The Aria-assigned identifier of the Master Plan Instance that will have payment responsibility for the assigned Plan.     

Required if the responsibility level (in the <resp_level_cd> field) is set to one of the two parent pay options.
 

 

The client-defined identifier of the Master Plan Instance that will have payment responsibility for the assigned Plan.    


Required if the responsibility level (in the <resp_level_cd> field) is set to one of the two parent pay options.
  alt_proration_end_date string 10

Date that proration should go up to in the yyyy-mm-dd format, Charges for the newPlanwill be prorated up to your specified <alt_proration_end_date>.

Example: If you are assigning a daily or weekly Plan, you can pass a date into this field to align the next bill date of the newPlanwith that of the customer's other daily or weekly Plan(s).

The start date of the next full invoice will be the day after your specified <alt_proration_end_date>.
  nso_fulfillment_date string 10 The date the Non Subscription Offering is fulfilled. A date in the past, present, or future can be specified.
  bank_acct_type string 32 The type of bank account being used (for primary_pay_method_type 2). 

Allowable values for bank_acct_type:

Values Description
savings savings
checking checking
business business
 

Output Arguments

Field Name Field Type Description
error_code long Aria-assigned error identifier. 0 indicates no error.
error_msg string Description of any error that occurred. "OK" if there was no error.
proration_result_amount double The currency amount of any resulting proration action performed as a result of the requestedPlanchange. ForPlanassignments 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 requestedPlanassignment/de-assignment were to be actually performed.
collection_error_code long If a collection is attempted, returns the error code associated with the collection.
collection_error_msg string The error message associated with collection_error_code.
statement_error_code long The error code if statement generation fails.
statement_error_msg string The text message associated with 'statement_error_code'
proc_cvv_response string The processor return code from CVV validation.
proc_avs_response string Processor return code from address validation
proc_cavv_response string The processors return code for security validation.
proc_status_code string The processor status code
proc_status_text string The processors status description
proc_payment_id string The processor payment ID
proc_auth_code string Authorization code provided by the issuing bank
proc_merch_comments string Additional information passed to payment processor
invoice_no long The Aria-assigned unique identifier of a given invoice.
expectd_activation_fee double The activation fee the account holder can expect based on the activation fees of the Plans on this invoice
expectd_mthly_recurring_cost double Regardless of the billing interval on the account, the monthly recurring cost of this change
expectd_annu_recurring_cost double  
acct_plan_line_items hash  
brd_arrow.gif line_no long The line number on the initial invoice
brd_arrow.gif line_type long Specifies the type of charge or credit associated with this line item.  

Allowable values for line_type:

Values Description
1 Recurring charge
2 Tax charge
3 Service credit
4 Coupon Credit
5 Activation Charge
6 Usage Charge
7 Recurring arrears charge
8 Order charge
9 Surcharge
brd_arrow.gif service_no long The unique ID for the service this line represents
brd_arrow.gif service_name string The name of the service this line represents
brd_arrow.gif line_units double The number of units of the item orPlanon this line
brd_arrow.gif rate_per_unit double The charge per unit of the item orPlanon this line
brd_arrow.gif line_amount double Specifies the total charge associated with this line item.
brd_arrow.gif line_base_units double Specifies the full, non-prorated number of units of the service code.
brd_arrow.gif proration_factor double Specifies the percentage of the line_base_units billed.
brd_arrow.gif description string The long description of this line, used when printing or otherwise displaying invoices
brd_arrow.gif date_range_start string The starting date range for the item orPlanon this line
brd_arrow.gif date_range_end string If any, the ending date range for the item orPlanon this line.
brd_arrow.gif credit_coupon_code string Specifies the coupon code applied to the invoice.
brd_arrow.gif plan_no long The unique IDPlanthis line represents
brd_arrow.gif plan_name string The name of thePlanthis line represents
brd_arrow.gif client_service_id string Client-defined unique service identifier.
brd_arrow.gif client_plan_id string Client-defined uniquePlanIdentifier
brd_arrow.gif po_num string Purchase order number assigned to the account orPlaninstance.
brd_arrow.gif bill_from_address_no long Address sent as the bill-from address to the tax engine for tax calculations. Depending on the taxation configuration, this parameter may return the Aria-assigned unique identifier of the service location for the invoice line item Note that service locations can be associated with a service for a givenPlaninstance on an account, with an item (NSO) purchased as part of a one-time order, or with a service as defined in the product catalog.
brd_arrow.gif ship_from_address_no long Address sent as the ship-from address to the tax engine for tax calculations. Depending on the taxation configuration, this parameter may return the Aria-assigned unique identifier of the service location for the invoice line item Note that service locations can be associated with a service for a givenPlaninstance on an account, with an item (NSO) purchased as part of a one-time order, or with a service as defined in the product catalog.
brd_arrow.gif bill_to_address_no long Address sent as the bill-to address to the tax engine for tax calculations. This parameter will return the Aria-assigned unique identifier of the contact on the account used as the bill-to address for the invoice line item.
brd_arrow.gif ship_to_address_no long Address sent as the ship-to address to the tax engine for tax calculations. This parameter will return the Aria-assigned unique identifier of the contact on the account used as the ship-to address for the invoice line item.
total_charges_before_tax double Total amount to be charged to the account before taxes have been calculated.
total_tax_charges double Total taxes as calculated for the amount of the transaction.
total_charges_after_tax double Total amount to be charged to the account after taxes have been calculated.
total_credit double The total amount of the credit to be applied to the account
total_tax_credit double The tax amount of the credit to be applies
total_credit_before_tax double The credit to be applied before tax is taken into account
total double The grand total of this invoice
proration_tax_amount double The pro-rated tax credit amount
proration_credit_result_amount double The total pro-rated credit amount
proration_credit_amount double The non-tax pro-rated credit amount
plan_instance_no long The unique identifier of thePlaninstance (can be either a master or Supplemental Plan) on which thePlanwill be replaced.
nso_order_no long The unique identifier for an order that is created for bundled NSOs.
nso_order_status_label string Status label for this order
proc_initial_auth_txn_id string 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.
Last modified

Tags

Classifications

This page has no classifications.
Powered by CXone Expert ®