Change Device Service Plan

PUT /devices/actions/plan

Changes the service plan for one or more devices.

Contents

See also:
Retrieve a List of Service Plans
Retrieve Information about Devices
Change Device Identifier

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 a device while its service is suspended.
  • Use separate requests to change 3G and 4G devices unless your account is set up to allow both types of devices in the same service plan.

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

The M2M Platform sends another asynchronous NiddService callback message for each NB-IoT device in the request, if the change is to add an NIDD price plan, and when NIDD Config for the device has been enabled.

Request Components

HTTP Request

PUT https://thingspace.verizon.com/api/m2m/v1/devices/actions/plan

Resource Path and Query Parameters

None.

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON.

 

Parameter Name Data Type Description
Authorization
required
string HTTP Authorization bearer token.
VZ-M2M-Token
required
string A valid session token returned by POST /session/login.
Content-Type
required
string Must be application/json.

Request Body

The request body identifies the devices that you want to change. You can either list individual devices, or work with all devices in an account or device group, and optionally filter by service plan or custom field values.

Parameter Name Data Type Description
devices
optional*
array of deviceIds objects A list of the devices that you want to change, specified by device identifier. You only need to provide one identifier per device. Do not use accountName, groupName, currentServicePlan, or customFields if you use this parameter.
kind,
id

required for devices
string The type and value of the device identifier.
  • ESN - decimal, 11 digits
  • ICCID - decimal, up to 20 digits
  • IMEI - decimal, up to 16 digits
  • MDN - decimal, 10 digits
  • MEID - hexadecimal, 14 characters
  • MSISDN - decimal, 11 digits
accountName
optional
*Recommended
string The name of a billing account.
This parameter is only required if the UWS account used for the current API session has access to multiple billing accounts.
An account name is usually numeric, and must include any leading zeros.

*By coding for the account number today, you prevent future code from breaking if you ever add a new sub-account.

groupName
optional*
string The name of a device group, if you want to restore service for all devices in that group.
currentServicePlan
optional*
string The name of a service plan, if you want to only include devices that have that service plan. You can use GET /plans to get a list of all service plans in the account.
customFields
optional*
list of customField objects Custom field names and values, if you want to only include devices that have matching values.
key
required for customFields
string The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
value
required for customFields
string The value of the custom field. The value is not case-sensitive, but other than that it must match exactly with the value set for a device. Wildcards and partial matches are not supported.
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.
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 GET /plans.
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 up to 10,000 individual devices with the devices parameter, or you can use any combination of groupName, currentServicePlan, and customFields to run the request on all devices that match all criteria.

Example Request Body

Change the service plan for a single device

{ "devices": [
 { "deviceIds": [
   { "id": "A100003685E561",
     "kind": "meid"
    }
   ]
   }
  ],
"servicePlan": "new_service_plan_code",
"carrierIpPoolName": "carrier_Ip_Pool_Name"
}

Change the service plan for two devices

{ "devices": [
  { "deviceIds": [
   { "id": "89148000000800259784",
     "kind": "iccid"
   } ]
  },
  { "deviceIds": [
   { "id": "89148000001134189816",
     "kind": "iccid"
   } ]
 } ],
   "servicePlan": "Tablet5GB",
   "carrierIpPoolName": "carrier_Ip_Pool_Name",
   "accountName": "0242078637-00001"
}

Move all devices with one service plan to another service plan

{
  "currentServicePlan": "existing_service_plan_code", 
  "servicePlan": "new_service_plan_code"
}

Success Responses

Status 200

Parameter Name Data Type Description
requestId string A unique string that associates the request with the results that are sent via a callback service. The ThingSpace Platform sends 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 have the same requestId.

Example Success Response

{ "requestId": "c8de7c1d-59b9-4cf3-b969-db76cb2ce509" }

CarrierService Callback Parameters

Parameter Name Data Type Description
requestId string

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

The ThingSpace Platform sends 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 have the same requestId.

 

deviceIds string

All the non-null device identifers for the device:

  • kind: the type of identifer (IMEI, IMSI, MIN, MDN, MSISDN, ICCID, EID)
  • id: a device identifer value
deviceResponse niddResponse object  Response object for CarrierService callbacks.
deviceResponse.changeServicePlanResponse niddResponse object Response object for CarrierService callbacks.
deviceResponse.changeServicePlanResponse.effectiveDate string The date and time the device restore is effective.

 

Example CarrierService Success Callback Response

{
   "username":"",
   "password":"",
   "requestId":"c8de7c1d-59b9-4cf3-b969-db76cb2ce509",
   "deviceIds":[
     { "id":"8586928930",
       "kind":"mdn"
     } ],
   "deviceResponse":
     { "changeServicePlanResponse":
       { "effectiveDate":"5/31/2018 12:00:00 AM" }
     }
}

niddService Callback Parameters

Parameter Name Data Type Description
requestId string

A unique string that associates the request with the NIDD information that is sent via a callback service.

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

 

niddResponse niddResponse object Response object for NiddService callbacks.
niddResponse.niddConfigResponse.accountName string The name of a billing account, which is usually in the format of 10 digits, a hyphen, and then five more digits. Must include any leading zeros.
niddResponse.niddConfigResponse.deviceIds array of device identifers

All the non-null device identifers for the device:

  • kind: the type of identifer (IMEI, IMSI, MIN, MDN, MSISDN, ICCID, EID)
  • id: a device identifer value
niddResponse.niddConfigResponse.reason string

Only appears if the status is "ConfigCreationFailed".


 Valid values include:

  • Internal error

  • NIDD configuration already exists

  • NIDD configuration not available.

status string

Nidd config response status. Valid values include:

  • ConfigCreated

  • ConfigCreationFailed

callbackCount integer Total number of callback requests.
maxCallbackThreshold integer Maximum number of callbacks allowed.

Example niddConfig Success Callback Response

{
  "username" : "user",
  "password" : "pwd",
  "requestId" : "3c5eef41-011c-4c20-8780-f4031180141b",
  "niddResponse" : {
    "niddConfigResponse" : {
      "accountName" : "9992330389-00001",
      "deviceIds" : [ {
        "id" : "99962019000000000000000000000002",
        "kind" : "EID"
      }, {
        "id" : "9996201900000000000345",
        "kind" : "IMEI"
      } ]
    }
  },
  "status" : "ConfigCreated",
  "callbackCount" : 1,
  "maxCallbackThreshold" : 4
}

Example niddConfig Failure Callback Response

{
  "username" : "user",
  "password" : "pwd",
  "requestId" : "4c5eef41-011c-2c20-8780-f4031180141b",
  "niddResponse" : {
    "niddConfigResponse" : {
      "accountName" : "9992330389-00001",
      "reason" : "Not CatM or NBIoT Device",
      "deviceIds" : [ {
        "id" : "99962019000000000000000000000002",
        "kind" : "EID"
      }, {
        "id" : "9996201900000000000345",
        "kind" : "IMEI"
      } ]
    }
  },
  "status" : "ConfigFailed",
  "callbackCount" : 1,
  "maxCallbackThreshold" : 4
}

Failure Responses

Status 400

All error messages are returned in this format:

{
      "errorCode": "error code string",
      "errorMessage": "error message string"
    }
    

Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.

Try It Out!