Skip to main content
Aria Knowledge Central

Subscription Portability


With Aria's Subscription Portability, you can move a customer's subscription/plan from one account to another in Aria. You might do this when a customer moves a phone connection from one subsidiary company to another, or to facilitate a change of ownership of a subscription.

How to Port a Customer's Subscription

You port a subscription by calling the API bulk_port_master_plan_instance_m, specifying a source account and pertinent plan details from that account, and a destination account. When successfully executed, this operation:

  • cancels the plan on the source account,
  • creates a new plan on the destination account,
  • notates the action in both accounts' Plan Histories in the Aria application, and
  • triggers related Event Notifications.

Post-Port Accounts Example

In the following example, the Master Plan Instance (Subscription) ported, Cable TV Monthly, included two Supplemental Plans (Add-ons): HBO and Shotime. Aria ported the entire plan hierarchy.

Source Account Post-Port

In the Source Account, Aria records entries in the Plan History for each plan-related event triggered by the Plan Instance Porting Manager.

Getting Here: [Source Account Overview] > Plans > Plan Historysub-port-cancelled.png

  1. Aria uses the values of Plan Instance Id for the plans being ported to populate the Client Defined Identifier on the destination account's new plan instances.
  2. Aria updates the Client Defined Identifier of plans being ported to a single Universally Unique Identifier (UUID).
  3. Aria cancels the plan on the source account.
  4. The Changed By column displays "Plan Instance Porting Manager" to advise the process that caused these changes.

Destination Account Post-Port

In the Destination Account, Aria records one entry in the Plan History indicating the Master Plan Instance that was ported.

Getting Here: [Destination Account Overview] > Plans > Plan History


  1. The Plan Instance Id for the Master Plan Instance is newly-created on the Destination Account.
  2. Note that the Client Defined Identifier is the Plan Instance Id value from the Source Account.
  3. Action displays "Master Plan Assigned via Porting."
  4. Action Details displays the Source Account number, Master Plan name, number of units of the plan, the plan status, the Rate Schedule name, Client-defined id, and Promo Code. In this example, no Promo Code is associated with the Master Plan Instance ported.
  5. The Changed By column displays "Plan Instance Porting Manager" to advise the process that caused these changes.

Best Practices

You should plan calls to bulk_port_master_plan_instance_m so the operation does not coincide with your daily batch processes. Because there is no bi-directional locking mechanism between the porting operation and your batches, the porting process stops itself when a daily batch is running, but the daily batch does not wait for the porting process to complete.

Important Notes

  • Aria does not carry over historical information for the plan you are porting (i.e., Financial Transactions history, Plan Instance history, Dunning history, Status history).
  • Aria assigns the new Master Plan Instance a new MPI number.
  • Aria retains the client-defined identifiers (CDIDs) of Plan Instances and Plan Unit Instances for the new MPI on the destination account.

    Note: Because there is client-level unique constraint on CDIDs, Aria updates the CDIDs of the source MPI with new universally unique identifiers (UUIDs) before creating the plan instance on the destination account.

  • Aria processes porting queues created by bulk_port_master_plan_instance_m in last-in-first-out (LIFO) order; that is, Aria uses the latest queue if there are multiple port requests for the same source MPI.
  • The porting process does not increment level counts on the destination MPI for catalog-level items such as total coupon uses or total promation registrations. These counts are transferred as they existing on the source account.
  • The process copies usage threshold, usage pooling, and pre-accumulation usage units to the new MPI so they will continue from where it was left on the source account.
  • Backdate usage rating will not work on the new plan because the rate history is not copied.
  • Aria will not automatically email customers to alert them the MPI was cancelled or the new ported MPI was created.
  • Data Extract events on both the source and new MPI will continue to happen.

Events and Notifications

If you have enabled the Account and Master Plan Instance Event Class, you can subscribe to two events (in event class version 3.4 or above) related to porting subscriptions. 

  • 758Account Master Plan Instance Porting Successful includes mpi_port_data, Master Plan Instance, Billing Group, and Dunning Group data
  • 759Account Master Plan Instance Porting Failed includes only mpi_port_data

Sample Payloads

XML format


Name-Value Pair Format


Email Format

MPI Port Fields
MPI Port Queue ID: 805
Source Acct Number: 7246
Source MPI Number: 9356
Source MPI CDID: 014E864A23A56D18E063D209140AAB88

Data Feed

Data Feed events on both the source and new MPIs will happen as previously designed. MPI tables involved in Data Feed are:

  • Was this article helpful?