Add Multiple Plans Immediately with Different Billing Intervals

Last updated
Save as PDF

Overview

If you have a customer who wants to purchase more than one Plan (product), you can assign Plans at the same time by calling the update_acct_plan_multi_m API once instead of calling separate APIs to assign one Plan at a time. The structure of the update_acct_plan_multi_m API is described in this walkthrough.

Notes:

Using the update_acct_plan_multi_m API will allow you to complete many updates in one call to avoid a lot of back and forth traffic between your system and Aria.
Aria recommends using lighter weight APIs (such as assign_acct_plan_m) that provide fewer details and may provide better performance by reducing the load on your system. This is a more incremental approach that involves calling a series of APIs to complete separate actions instead of completing multiple actions at the same time using 1 API.

Example: Instead of calling the update_acct_plan_multi_m API to assign 3 Plans at the same time as shown in the sample call below, you can call the assign_acct_plan_m API 3 times in a row to assign those same 3 Plans separately, as briefly described here:
- Assign a new Master Plan (MP) and align its anniversary date with that of pre-existing MP by passing the Plan instance number of the pre-existing MP into the <override_dates_mp_instance_no> field.
- Then assign 2 new Supplemental Plans and specify that they should be associated with the newly-assigned MP by passing the Plan instance number of that MP into the <parent_plan_instance_no> field.

Depending on your product structure, you might have Plans with different billing periods. You may decide that, to avoid billing the customer on too many different dates, you want to align the billing dates of the new Plans with the billing date of an existing Master Plan on the account.

You may also want to prorate the charges for the new Plans if you assigned them in the middle of an existing billing period.

In the sample call shown below, for demonstration purposes, we will use the update_acct_plan_multi_m API to assign these Plans that will go into effect immediately: an annual Master Plan, a quarterly Supplemental Plan, and a monthly Supplemental Plan.

Instructions

Sample Call

A. Complete the prerequisites

Authenticate the customer logging into your user self-service (USS) application by calling the set_session_auth_m API.
Call the get_acct_details_all_m API to obtain the customer's billing group and dunning group information.
Call the get_client_plans_basic_m API to obtain the Plans that the customer can add.

B. Call the update_acct_plan_multi_m API as follows:

Pass in your client number and authorization key:

<lit:client_no>12345_sample_client_no</lit:client_no>
<lit:auth_key>AbCdEfG_sample_auth_key</lit:auth_key>

Identify the customer who is adding Plans by passing in the customer's account number as shown below:
```
 <lit:acct_no>3374227</lit:acct_no>
```

In the first <plan_updates> array, pass in arguments as described below to assign the first Plan. In this example, we will assign an annual Master Plan first.

Specify the action that you want to take on the Plan. In this example, we will pass "1" into the <plan_directive> field, which means that we are assigning the Plan.
```
<lit:plan_directive>1</lit:plan_directive>
```

Pass in your chosen Plan identifier that you can use to reference the Master Plan multiple times in this call. In this example, we will pass "1" into the <plan_instance_idx> field to identify the Master Plan being assigned. This identifier will then be passed into additional fields described below to associate the Supplemental Plans with this Master Plan.
```
 <lit:plan_instance_idx>1</lit:plan_instance_idx>
```

Identify the new Master Plan to be assigned as shown below. Pass the Plan identifier into the <new_plan_no> or <new_client_plan_id> field.
Obtain the identifier of the new Plan from the <plan_no> field returned by the get_client_plans_basic_m API.

Note: Pass in the Master Plan before the Supplemental Plan, as shown below. That way you won't get an error because you tried to assign a Supplemental Plan before its corresponding Master Plan.

<lit:new_plan_no>161832</lit:new_plan_no>
<lit:new_client_plan_id></lit:new_client_plan_id>

Identify the quantity of the new product that the customer wants to purchase as shown below. Pass the requested number of Plan units into the <plan_units> field.
```
<lit:plan_units>1</lit:plan_units>
```

Specify the status that the new Plan should be in as shown below. In this example, the Plan status is active (1).
```
<lit:plan_status_cd>1</lit:plan_status_cd>
```

Specify the billing group to be associated with the new Plan as shown below:
This will ensure that payments for the new Plan are made using the payment method associated with that billing group.

Obtain the billing group identifier from the <billing_group_no> or <client_billing_group_id> field returned by the get_acct_details_all_m API.
```
<lit:billing_group_no>1598765</lit:billing_group_no>
```

Specify the dunning group to be associated with the new Plan as shown below.
This will ensure that if the customer is behind on payments for this new Plan, Aria will take actions on the account as you specified in the dunning process associated with that dunning group.

Obtain the dunning group identifier from the <dunning_group_no> or <client_dunning_group_id> field returned by the get_acct_details_all_m API.
```
<lit:dunning_group_no>1751952</lit:dunning_group_no>
```

For your reference, all of the fields passed into the first <plan_updates> array, in this example, are shown together below:

In the second and third <plan_updates> arrays, pass in arguments as described below to assign additional Plans. In this example, we will assign a quarterly Supplemental Plan and a monthly Supplemental Plan.

Specify the action that you want to take on the Plan. In this example, we will pass "1" into the <plan_directive> field, which means that we are assigning the Plan.
```
<lit:plan_directive>1</lit:plan_directive>
```

Identify the new Supplemental Plann to be assigned as shown below. Pass the Plan identifier into the <new_plan_no> or <new_client_plan_id> field.
Obtain the identifier of the new Plan from the <plan_no> field returned by the get_client_plans_basic_m API.
```
<lit:new_plan_no>139819</lit:new_plan_no>
<lit:new_client_plan_id></lit:new_client_plan_id>
```

Identify the quantity of the new product that the customer wants to purchase as shown below. Pass the requested number of Plan units into the <plan_units> field.
```
<lit:plan_units>1</lit:plan_units>
```

Specify the Master Plan with which the Supplemental Plan should be associated as shown below. Find the identifier that you passed into the <plan_instance_idx> field in the first <plan_updates> array and pass it into the <parent_plan_instance_idx> field.
```
<lit:parent_plan_instance_idx>1</lit:parent_plan_instance_idx>
```

Specify the status that the new Supplemental Plan should be in as shown below. In this example, the Plan status is active (1).
```
<lit:plan_status_cd>1</lit:plan_status_cd>
```

For your reference, all of the fields passed into the second and third <plan_updates> arrays, in this example, are shown together below:

Pass in the following additional arguments:

Specify when the three new Plan assignments should take place and which proration rule should be applied as shown below. In this example, we will set the <assignment_directive> to "4", which means that the three Plans will go into effect immediately with a prorated invoice.

Notes:

If you do not pass in an <assignment_directive>, then by default:
- A new Master Plan will go into effect on the day on which you called the API (current date).
- A new Supplemental Plan will go into effect on the corresponding Master Plan's next anniversary date (plus the number of billing periods that you passed into the <offset_interval> field, if any).
The proration rule that you specify will match or override your Invoicing Options On New Master Plan Assignment parameter (in the Aria application under Configuration > Billing > Invoice Settings).

<lit:assignment_directive>4</lit:assignment_directive>

Specify whether to align the new Master Plan's anniversary date with any existing Master Plan's anniversary date as shown below. In this example, we will align the new Master Plan's anniversary date with the anniversary date of Master Plan Instance number "4251245". To do so, we will pass that number into the <override_dates_mp_instance_no> field.

Note: If you do not pass in an <override_dates_mp_instance_no> then, by default, the anniversary date of the new Master Plan will be set to the Plan assignment date (current date or your specified future date or retroactive date).

<override_dates_mp_instance_no>4251245<override_dates_mp_instance_no>

Specify which proration rule should be applied as shown below. This additional input is required if you want a prorated invoice and the Plan assignment will not take place in the future. In this example, we will pass "2" into to the <invoicing_option> field, which means that prorated invoicing will be performed.

Note: The proration rule that you specify will match or override your client setting for proration.

<lit:invoicing_option>2</lit:invoicing_option>

For your reference, all of the additional fields passed into the API, in this example, are shown together below:

Sample Response

You can check the customer's account in the Aria application to confirm that the Plan additions were completed correctly as described in the use case above.

Note: On the new Master Plan's anniversary date, Aria will create a full invoice for all three Plans. Then Aria will bill the customer monthly, quarterly, and annually based on each Plan's billing interval.

Example: You assigned the three Plans on 17 May 2019. You aligned the Master Plan's anniversary date with a previously-assigned Master Plan whose anniversary date is on the 16th. Aria will create invoices for the new Plans as follows:

prorated invoice for all three new Plans covering 17 May 2019 to 15 June 2019;
full invoice created on 16 June 2019 for all three Plans (covering 1 year for the annual Plan, 3 months for the quarterly Plan, and 1 month for the monthly plan);
full invoice created on 16 July 2019 for only the monthly Plan (and, for the monthly Plan, on the 16th of every month after that);
full invoice created on 16 September 2019 for only the new monthly and quarterly Plans (and for quarterly Plan, on the 16th of the month, every 3 months after that);
if the customer renews all 3 Plans, full invoice created on 16 June 2020 for all three Plans (covering 1 year for the annual Plan, 3 months for the quarterly plan, and 1 month for the monthly Plan).