t ChangeDeviceServicePlan

ChangeDeviceServicePlan

Sets a new service plan for one or more devices.

Uses and Requirements

You can change the service plan for an active device up to four times per month. You cannot change the service plan for device while its service is suspended. For more information, see M2M Service Provisioning Rules.

The ThingSpace Platform sends a CarrierService callback message for each device in the requuest when the service plan has been changed, or if there was a problem and the change could not be completed.

Request Parameters

Parameter Type Description
DeviceList
optional*		 DeviceIdentifierCollection

A list of the devices that you want to change, specified by device identifier. Do not pass DeviceGroupName, AccountName, DeviceCustomFieldFilter, or DeviceServicePlanFilter if you use this parameter.

You can use GetDeviceList to get a list of all devices in the account.

For each device in DeviceList, use this structure of nested parameters: 

<DeviceIdentifierCollection>
  <DeviceIndentifiers>
    <DeviceIdentifier>
      <Kind></Kind>
      <Identifier></Identifier>
    </DeviceIdentifier>
  </DeviceIndentifiers>
</DeviceIdentifierCollection>
Kind
required for DeviceList		 string The type of the device identifier. Valid types of identifiers are:

  • ESN (decimal)
  • ICCID (up to 20 digits)
  • IMEI (up to 16 digits)
  • MDN
  • MEID (hexadecimal)
  • MSISDN

    • For 2G and 3G devices, you only need to include one Kind and Identifier. For 4G devices, you must specify both the IMEI and the ICCID within separate DeviceIdentifier elements, in that order.
Identifier
required for DeviceList		 string The value of the device identifier.
DeviceGroupName
optional*		 string The name of a device group, if you want to only include devices in that group. You can use GetDeviceGroupList to get a list of all device groups in the account.
AccountName
optional*		 string

The name of a billing account if you want to change all devices in that account. An account name is usually numeric, and must include any leading zeros.

This parameter is required if you are passing DeviceGroupName and you have access to multiple accounts, since the same device group name can exist in multiple accounts.
DeviceServicePlanFilter
optional*		 string A service plan code,, if you want to only include devices that have that service plan. You can use GetServicePlanList to get a list of all service plans in the account.
DeviceCustomFieldFilter
optional*		 CustomFieldFilterObject The names and values of custom fields, if you want to only include devices that have matching custom fields.
Name
required for DeviceCustomFieldFilter		 string The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
Value
required for DeviceCustomFieldFilter		 string

The value of the custom field. Allowed characters in custom field values:

  • Alphanumeric characters
  • / (forward slash)
  • SPACE
  • @ (at sign)
  • . (period)
  • , (comma)
  • : (colon)
  • - (hyphen)
  • _ (underscore)
  • ( (open parenthesis)
  • ) (close parenthesis)
  • [ (open bracket)
  • ] (close bracket)
  • # (number sign or hash)
ServicePlan
required		 string

The service plan code that you want to assign to all specified devices. Set this parameter to one of the Code values returned by GetServicePlanList in the Account Service.

Verizon Wireless provides service plan codes at the time of on-boarding and subsequently whenever there are any changes to the service plan.
CarrierIpPoolName
*optional		 string The private IP pool (Carrier Group Name) from which your device IP addresses will be derived. If you do not include this element, the default pool will be used.

* This field is required if using the ipAddress parameter.
FeatureCodesToAdd
optional		 string Not currently in use
FeatureCodesToRemove
optional		 string Not currently in use
TakeEffect
optional		 string

Set to "BackDate" to make the service plan change effective at the beginning of the current billing cycle. This is recommended if you anticipate devices using more than the monthly allowance of the current plan and want to change to a plan with a higher monthly allowance to avoid overage charges.

NOTE: You cannot backdate to a service plan with a lower monthly allowance.

* You can either specify individual devices with the DeviceList parameter, or you can run the request on all devices that have a specified account name, device group name, service plan name, or custom field value. You can specify an AccountName or a DeviceGroupName plus one or both filters to identify only those devices that match all criteria.

Response Parameters

Parameter Type Description
RequestId string

A unique string that associates the request with the results that are sent via a callback service.

The ThingSpace Platform will send a separate callback message for each device that matched the request criteria, indicating whether the operation succeeded for that device and containing any requested information. All of the callback messages will have the same RequestId.

Callback Response Parameters

Parameter Type Description
CallbackRequest CallbackRequest Wrapper element for all callback elements.
Username string The username defined when a URL was registered for the callback service, or an empty element if no username was defined.
Password string The password defined when a registered for the callback service, or an empty element if no password was defined.
RequestId string A unique string that matches the RequestId returned in the synchronous response to the original API request.

A separate callback message is sent for each device that matched the request criteria, indicating whether the operation succeeded for that device. All of the callback messages will have the same RequestId.
Device DeviceIdentifier The device that was changed.
Kind string The type of the device identifier. Valid types of identifiers are:
  • ESN (decimal)
  • ICCID (up to 20 digits)
  • IMEI (up to 16 digits)
  • MDN
  • MEID (hexadecimal)
  • MIN
  • MSISDN
Identifier string The value of the device identifier.
Data CallbackData The data elements for this callback.
CarrierService CarrierServiceCallbackRequest The data returned from a CarrierService API request.
ChangeDeviceState ChangeDeviceStateResponse Null for ChangeDeviceServicePlan requests.
ChangeDeviceFeatureCodes ChangeDevicefeatureCodesResponse Null for ChangeDeviceServicePlan requests.
ChangeDeviceServicePlan ChangeDeviceServicePlanResponse Information about the service plan change.
ServicePlan string The code of the new service plan.
EffectiveDate string The date and time that the service plan change will take effect.
ChangeDeviceCostCenter ChangeDeviceCostCenter Response Null for ChangeDeviceServicePlan requests.
ChangeDeviceCustomFields ChangeDeviceCustomFieldsResponse Null for ChangeDeviceServicePlan requests.
ChangeDeviceIdentifier ChangeDeviceIdentifierResponse Null for ChangeDeviceServicePlan requests.
Change4GDeviceIdentifier Change4GDeviceIdentifierResponse Null for ChangeDeviceServicePlan requests.
MoveDevice MoveDeviceResponse Null for ChangeDeviceServicePlan requests.
ExternalProvisioningChange ExternalProvisioningChange Null for this callback service.
PromoChange PromoChange Null for this callback service.
SMSDelivery SMSDelivery Null for this callback service.
PRLInformation PRLInformation Null for this callback service.
DeviceSuspendStatus DeviceSuspendStatus Null for this callback service.
Fault SoapFault Information about any errors that may have occurred.
faultcode QName
faultstring string
faultfactor anyURI
detail
Comment string Null for this callback service.
Summary SummaryReport Null for this callback service.
Status string Null for ChangeDeviceServicePlan requests.
CallbackCount integer The number of times this callback message has been sent.
MaxCallbackThreshold integer The maximum number of times this callback message will be sent if it is not correctly acknowledged.

Example SOAP Request 

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:v2="http://nphase.com/unifiedwebservice/v2"
      xmlns:nph="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.CarrierService"
      xmlns:nph1="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common"
      xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
      <soapenv:Header>
        <v2:token>03e0385d-9649-4d88-a977-6a0596cc38ab</v2:token>
      </soapenv:Header>
      <soapenv:Body>
        <v2:ChangeDeviceServicePlan>
          <v2:Input>
            <nph:DeviceList>
              <nph1:DeviceIdentifierCollection>
                <nph1:DeviceIdentifiers>
                  <nph1:DeviceIdentifier>
                    <nph1:Kind>meid</nph1:Kind>
                    <nph1:Identifier>270113177710066329</nph1:Identifier>
                  </nph1:DeviceIdentifier>
                </nph1:DeviceIdentifiers>
              </nph1:DeviceIdentifierCollection>
            </nph:DeviceList>
            <nph:ServicePlan>m2m</nph:ServicePlan>
    <nph:CarrierIpPoolName>SampleCarrierIpPoolName</nph:CarrierIpPoolName>
          </v2:Input>
        </v2:ChangeDeviceServicePlan>
      </soapenv:Body>
    </soapenv:Envelope>

Example SOAP Response 

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <ChangeDeviceServicePlanResponse xmlns="http://nphase.com/unifiedwebservice/v2">
      <Output xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:a="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.CarrierService">
       <a:RequestId>857c384c-b650-4c0c-aed3-53264d1087bc</a:RequestId>
      </Output>
    </ChangeDeviceServicePlanResponse>
  </s:Body>
</s:Envelope>

Example SOAP Callback 

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <CallbackRequest xmlns="http://nphase.com/unifiedwebservice/v2">
      <Username/>
      <Password/>
      <RequestId>c8de7c1d-59b9-4cf3-b969-db76cb2ce509</RequestId>
      <Device>
        <Kind>mdn</Kind>
        <Identifier>8586928930</Identifier>
        </Device>
      <Data>
        <Data>
          <CarrierService>
            <ChangeDeviceState xsi:nil="true"/>
            <ChangeDeviceFeatureCodes xsi:nil="true"/>
            <ChangeDeviceServicePlan>
              <ServicePlan>M2M2GB</ServicePlan>
              <EffectiveDate>M2M2GB</EffectiveDate>
            </ChangeDeviceServicePlan>
            <ChangeDeviceCostCenter xsi:nil="true"/>
            <ChangeDeviceCustomFields xsi:nil="true"/>
            <ChangeDeviceIdentifier xsi:nil="true"/>
            <Change4GDeviceIdentifier xsi:nil="true"/>
            <MoveDevice xsi:nil="true"/>
          </CarrierService>
          <ExternalProvisioningChange xsi:nil="true"/>
          <PromoChange xsi:nil="true"/>
          <Fault xsi:nil="true"/>
          <Comment>Success</Comment>
          <Summary xsi:nil="true"/>
          <Status xsi:nil="true" />
          <CallbackCount>1</CallbackCount>
          <MaxCallbackThreshold>4</MaxCallbackThreshold/>
        </Data>
      </Data>
    </CallbackRequest>
  </s:Body>
</s:Envelope>

Request Schema Diagram

Response Schema Diagram