update_acct_plan_multi_m Walkthrough
Overview
You can complete multiple user self-service (USS) use cases at the same time by calling the API update_acct_plan_multi_m API once instead of calling separate APIs to complete individual USS use cases.
Here is an example showing how to use the update_acct_plan_multi_m API to assign multiple Plans at the same time.
For more information about assigning Master Plan and Supplemental Plans with different date options using the update_acct_plan_multi_m API, see update_acct_plan_multi_m Use Cases.
Notes: When you call the update_acct_plan_multi_m API, be aware of the following:
- This 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.
Here are some sample USS use cases in which separate, lighter weight APIs are called.
- When you assign a Master Plan immediately and you want to prorate the invoice, you must pass 2 into the <invoicing_option> field even if you passed in an <assignment_directive> that includes proration. For other actions involving Master Plans or Supplemental Plans, you only need to pass in an <assignment_directive> to create a prorated invoice.
- If you assign a Master Plan along with a Supplemental Plan that has a billing interval greater than one month, the Supplemental Plan will be billed only for the first month unless you pass in <offset_months>. That is because the default proration behavior of this API is to invoice only up to the nearest bill day unless you specify the <offset_months>.
Example: if you assign a quarterly Master Plan and a quarterly Supplemental Plan, the Supplemental Plan will be billed only for the first month unless you pass 2 into the <offset_months> field in the <plan_updates> array for the Supplemental Plan.
Best Practices
For best results when calling the update_acct_plan_multi_m API, keep these key points in mind and follow these guidelines:
- Pass values into the API in the order in which you want actions to take place.
Example: if you want to replace a Master Plan (MP), then assign a Supplemental Plan (SP) associated with the MP, pass in the MP action first or you will get an error message because the account's current MP is not associated with the SP.
- In the <plan_updates> array, pass in a Plan instance only once with one <plan_directive>. If you pass in the same Plan instance multiple times, each with a different, conflicting <plan_directive>, an error will occur.
Example: you cannot update and cancel the same Plan instance within the same call.
- This API can generate only real invoices and not pending invoices. Therefore, you may choose to pass false into the <do_write> field to allow your customer to confirm changes first. Then call the API again with the <do_write> field set to true so that the requested action(s) can be taken and an invoice can be generated.
- If a collection fails, Aria will roll back all of the requested changes to the Plans associated with the billing group whose collection failed. In such a situation, you may choose to use error handling in your USS application to take corrective action.
Example: ask the customer to use a different payment method.
- If you are adding multiple master and Supplemental Plans using this API, make sure that they all have the same assignment directive/start date, billing date, and proration rule. You cannot pass in multiple Plans, each with a different <assignment_directive>, <retroactive_start_date>, <alt_bill_day>, and/or <invoicing_option>. However, each Master Plan can have its own unique <effective_date> with the same <assignment_directive>.
If you need to add multiple Plans, each with a different <assignment_directive>, <retroactive_start_date>, <alt_bill_day>, and/or <invoicing_option>, call the update_acct_plan_multi_m API with only one Plan action or use a lighter weight API such as assign_acct_plan_m.
API Description
The diagram below identifies some key sections and fields within the update_acct_plan_multi_m API that you can use to add/update Plans and change billing options.
Notes:
- You can click on the diagram to see a larger version of it. You will be prompted to open the diagram in your chosen browser or to save the diagram.
- Please see the update_acct_plan_multi_m API documentation for detailed information about additional available fields.
