changePlan()

ManagedPlanChangeResponse changePlan(string usn, string managedPlanChoiceId, PaymentRequest paymentRequest, PlanOptions planOptions)

This method changes the plan of the specified subscription.

Parameters

usn: Format: string; Purpose: Specifies the USN of the subscription.
managedPlanChoiceId: Format: string; Purpose: Specifies the ID of a managed plan choice.
paymentRequest: Format: PaymentRequest XML; Purpose: (Optional) Defines a PaymentRequest XML document that specifies the payment details for the plan change.
Note: Required if the plan change requires pre-payment before processing the change.
planOptions: Format: PlanOptions XML; Purpose: (Optional) Defines a PlanOptions XML document that specifies plan option overrides for the plan change.
The PlanOptions XML type is ObjectType. Plan options and sub-elements can only be boolean or integer, with name as the name of the option, and the value is the value of the option.

Note: This element is optional, but as a plan can specify that certain plan options are required, billing errors may be produced if required options are not correctly configured.

Results

This method returns a ManagedPlanChangeResponse XML document that details the plan change, for example, invoice and payment details.

Smile emits a SubscriptionPlanChanged message after the plan is changed. If the plan change results in the subscription's features to change Smile emits the SubscriptionFeaturesChanged message. If this method raises financial transactions, Smile emits the TransactionClosed message.

Example: A returned ManagedPlanChangeResponse XML document

This example shows a ManagedPlanChangeResponse XML document.

<ManagedPlanChangeResponse xmlns="http://xml.inomial.com/smile/2.xsd" xmlns="http://ws.inomial.com/smile.2">
  <PlanScheduleItem>
    <PlanCode>tp6282</PlanCode>
    <PlanScheduleType>1</PlanScheduleType>
    <Start>2014-12-01T00:00:00.000+11:00</Start>
    <Options>
      <Object/>
    </Options>
    <PlanScheduleItem>1079</PlanScheduleItem>
  </PlanScheduleItem>
  <Invoice>
    <version>2.0</version>
    <transactionType>Quote</transactionType>
    <company>1</company>
    <usn>2142422415</usn>
    <transactionNumber>21429915</transactionNumber>
    <currency>AUD</currency>
    <amount>0.10</amount>
    <accountType>1</accountType>
    <gstAmount>0.01</gstAmount>
    <salesReportCategory>invoice</salesReportCategory>
    <formattedAmount currency="AUD" formatted="$0.10">0.10</formattedAmount>
    <formattedGstAmount currency="AUD" formatted="$0.01">0.01</formattedGstAmount>
    <unallocatedAmount>0.10</unallocatedAmount>
    <formattedUnallocatedAmount currency="AUD" formatted="$0.10">0.10</formattedUnallocatedAmount>     
    <transactionDate>2014-12-17+11:00</transactionDate>
    <openDate>2014-12-17+11:00</openDate>
    <quoteNumber>21429915</quoteNumber>
    <createdByUsn>2142420781</createdByUsn>
    <transactionItem>
      <usn>2142422423</usn>
      <lineNumber>0</lineNumber>
      <itemCode>004691</itemCode>
      <chargeFrom>2014-12-17+11:00</chargeFrom>
      <chargeTo>2014-12-17+11:00</chargeTo>
      <description>Invoice item description</description>
      <quantity>1</quantity>
      <currency>AUD</currency>
      <amount>0.10</amount>
      <isGst>false</isGst>
      <chargeGst>true</chargeGst>
      <discount>0</discount>
      <count>0</count>
      <gstAmount>0.01</gstAmount>
      <salesReportCategory>unknown</salesReportCategory>
    </transactionItem>
    <transactionItem>
      <usn>2142422423</usn>
      <lineNumber>1</lineNumber>
      <itemCode>round</itemCode>
      <chargeFrom>2014-12-17+11:00</chargeFrom>
      <chargeTo>2014-12-17+11:00</chargeTo>
      <description>Rounding adjustment</description>
      <quantity>1</quantity>
      <currency>AUD</currency>
      <amount>-0.01</amount>
      <isGst>false</isGst>
      <chargeGst>true</chargeGst>
      <discount>0</discount>
      <count>0</count>
      <gstAmount>0</gstAmount>
      <salesReportCategory>round</salesReportCategory>
    </transactionItem>
    <transactionItem>
      <usn>2142422423</usn>
      <lineNumber>2</lineNumber>
      <itemCode>gst</itemCode>
      <chargeFrom>2014-12-17+11:00</chargeFrom>
      <chargeTo>2014-12-17+11:00</chargeTo>
      <description>Includes 10% GST</description>
      <quantity>1</quantity>
      <currency>AUD</currency>
      <amount>0.01</amount>
      <isGst>true</isGst>
      <chargeGst>false</chargeGst>
      <discount>0</discount>
      <count>0</count>
      <gstAmount>0.00</gstAmount>
      <salesReportCategory>gst</salesReportCategory>
    </transactionItem>
  </Invoice>
</ManagedPlanChangeResponse>

Faults

NoSuchItemException

This fault is returned when the USN provided does not have a corresponding subscription, or managed plan change choice ID does not have a corresponding managed plan change choice.

PlanChangeUnavailableException

This fault is returned when the subscription is not eligible for plan changes. For example, if the subscription does not belong to a plan change group.

PlanChangeException

This fault is returned when an internal error or configuration problem prevents the request from being processed.

InvalidRequestException

This fault is returned when the plan change request is invalid. For example, when the provided USN is an account.

Java client syntax

java -cp build/smilewsv2-client.jar [options] com.inomial.smile.client.v2.examples.ChangePlan usn managedPlanChoiceId [paymenRequest] [filename]

usn: Purpose: Specifies the USN of the subscription.
managedPlanChoiceId: Purpose: Specifies the ID of the managed plan choice.
paymentRequest: Purpose: (Optional) Defines the filename of the PaymentRequest XML document.
filename: Purpose: (Optional) Defines the filename of the PlanOptions XML document.

Note: For more information about the Java client and the options it accepts, see Java client syntax.