- 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 in the Aria UI, click Configuration > Billing > Invoice Settings.
-
The Discount Rule override feature is available for both Master Plan Instance stack level and Plan Instance level coupons.
-
If the coupon <assignment_scope> includes mandatory supplemental plans, then the Discount Rule overrides given for the parent will be carried to those mandatory supplemental plans also.
-
Future assignment directives give first precedence to the <coupon_codes_override_discount_rules> input for MPI stack level coupons but not plan-instance-level coupons. To assign plan-instance-level coupons in the future, assign the coupon without the <coupon_codes_override_discount_rules>.
assign_acct_plan_m Guide
The assign_acct_plan_m API assigns a new master or supplemental plan to the specified account.
When you assign a new plan to 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, including the application of coupons at the plan instance level
- NSO and SKU information
| API Specification: | |
| Required Fields: |
|
| Error Messages: | assign_acct_plan_m Error Messages |
Additional Guidance
Input Fields
| Field Name | Notes | ||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
<coupon_codes_override_discount_rules> (array) > (<coupon_code>, <assignment_scope>, <override_discount_rule_scope> (array)) |
Allowable Values for <assignment_scope>
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <existing_primary_payment_method_no> | The same pay method sequence number cannot be used for the primary and secondary payment method. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| <existing_client_primary_payment_method_id> | The same pay method sequence number cannot be used for the primary and secondary payment method. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| <existing_backup_payment_method_no> | The same pay method sequence number cannot be used for the primary and secondary payment method. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| <existing_client_backup_payment_method_id> | The same pay method sequence number cannot be used for the primary and secondary payment method. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| <existing_dunning_group_no> | You must associate Dunning Groups with parent-pay Master Plan Instance. If you do not specify a Dunning Group when assigning an Master Plan Instance, the system will create an empty Dunning Group (i.e., without any values in the attributes) and assign it to that Master Plan Instance automatically, without issuing an error or warning. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| <existing_client_def_dunning_group_id> | You must associate Dunning Groups with parent-pay Master Plan Instances. If you do not specify a Dunning Group when assigning a Master Plan Instance, the system will create an empty Dunning Group (i.e., without any values in the attributes) and assign it to that Master Plan Instance automatically, without issuing an error or warning. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| <resp_level_cd> |
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>. See Parent-child Account Best Practices for more information. |
||||||||||||||||||||||||||||||||||||||||||||||||||
| <offset_months> | 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 a Plan with a daily, weekly, or any other billing interval. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| <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. |
||||||||||||||||||||||||||||||||||||||||||||||||||
| <collection_group_bg_row> (array) |
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <bill_lag_days> | 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. See Bill Lag Days for more information. | ||||||||||||||||||||||||||||||||||||||||||||||||||
|
<proc_field_override> (array)
|
If you use the Chase Paymentech or Vantiv Payment Gateway, 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). The value that you pass into this field will override the Recurring Options that you set in the Aria application under:
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:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <resp_master_plan_instance_no> | Required if the responsibility level (in the <resp_level_cd> field) is set to one of the two parent pay options. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| <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. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| <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 new Plan with 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>. |
||||||||||||||||||||||||||||||||||||||||||||||||||
| <notify_method> |
How the client communicates with the account holder. If a notification method is not provided, this value defaults to "1" (HTML email). Allowable values:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <primary_pay_method_type> |
This is the method_id corresponding to a payment method such as credit card, Electronic Check, Pre-Paid, Net Terms, etc. Allowable values:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <status_until_alt_start> |
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:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <invoicing_option> |
Indicator for performing full invoicing, and Perform Prorated Invoicing or client-defined on this account as part of this call. Allowable values:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <resp_level_cd> |
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:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <plan_status> |
Updates thePlanstatus for thePlanInstance. Allowable values:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <assignment_directive> |
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:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <do_write> |
Boolean indicator that specifies whether to actually perform the requested operation. If 'false' is passed in this field, Aria calculates, if applicable, any potential effects from this call such as proration, 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:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <auto_offset_months_option> |
Automatically set the offset for the billing anniversary month. Allowable values:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <usage_pooling> |
Indicates whether usage pooling is enabled for this Plan instance. Allowable values:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <usage_threshold_applicability> |
Usage tracking options on the Plans in the account Allowable values:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <nso_bill_immediately> |
Indicates whether to bill the NSO items immediately or if not set bill on next billing anniversary date. Allowable values:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <proration_invoices_timing> |
Determines whether to create a separate invoice for prorated charges immediately, or defer to the next anniversary date. Note that this will override the Proration Invoice Timing configuration saved with thePlanin the product catalog. Allowable values:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <cc_id> |
A numeric code indicating the type of credit card. Allowable values:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <combine_invoices> |
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:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <force_master_bill_date_reset> |
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:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <recurring_process_model_ind> |
Defines a recurring payment type for Credit Card and Tokenized Credit Cards. Allowable values:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <usage_accumulation_reset_months_renewal_option> |
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:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <transaction_type> |
Allowable values:
|
||||||||||||||||||||||||||||||||||||||||||||||||||
| <bank_acct_type> |
The type of bank account being used (for primary_pay_method_type 2). Allowable values:
|
Output Fields
| Field Name | Notes | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| <line_type> |
Specifies the type of charge or credit associated with this line item. Allowable values:
|