Standard APIs5G Business InternetAPI Reference
Change Service Plan for 5G Business Internet
Change a 5G Business Internet Service Plan
PUT /devices/actions/plan
Changes the service plan for one or more 5G Business Internet devices.
Uses and Requirements
- The service plan can be changed for an active device up to four times per month.
- Changing an individual device to a 5G Business Internet unlimited plan requires address qualification. Please note that these plans are fixed location plans. It is agreed to only use the service at the qualified service address that Verizon Wireless approved at the time the service was activated. If the service is used outside of the qualified service address without the specific written approval of Verizon Wireless, Verizon Wireless reserves the right to terminate the Service at any time thereafter upon written notice.
- The service plan cannot be changed for a device while its service is suspended.
Note: When using SKU based activations, SIM OTA (Over-The-Air) must be performed prior to performing maintenance transactions (Service Plan change, feature change, ICCID change.)
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. To learn more about callbacks, please visit About Callback Services.
Header Parameters
The request header must set the content-type to JSON, contain a current ThingSpace authorization token and a current VZ-M2M session token. For more details on how to get these tokens, visit Getting Started.
| Parameter Name | Data Type | Description |
|---|---|---|
| Authorization (required) | string | HTTP Authorization request header containing a valid Bearer token: Authorization: Bearer {token} |
| VZ-M2M-Token (required) | string | A valid session token returned by a Connectivity Management POST /session/login request. |
| Content-Type (required) | string | Must be application/json. |
HTTP Request
POST https://thingspace.verizon.com/api/m2m/v1/devices/actions/plan
Request Parameters
The request body identifies the devices to change service plans for. 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. All fields are required unless marked "optional".
| Parameter Name | Data Type | Description |
|---|---|---|
| accountName (optional but recommended) | string | The name of a billing account. This value is numeric and must include any leading zeroes. This parameter is only required if the UWS account used for the current API session has access to multiple billing accounts. Using this field is recommended. By coding for the account number, future code is prevented from breaking if a new sub-account is added. |
| servicePlan | string | The service plan code to assign to all specified devices. Set this parameter to one of the code values returned by GET /plans/{accountname}. Verizon Wireless provides service plan codes at the time of on-boarding and subsequently whenever there are any changes to the service plan. NOTE: Any devices in the request that are not supported by the service plan will not activate. |
| deviceListWithServiceAddress | array | An array of Device ID information and customer information objects, including the object defining the address of where the device will be used. |
| deviceIds | array | An array of Device ID objects including an id and kind. A kind is the type of device identifier. Valid values include: imei (decimal, 15 digits) and iccid (decimal, 20 digits). If both are used they should be listed in that order. The id is the value of those types. |
| primaryPlaceOfUse | object | The customer name and the address of the device’s primary place of use. |
| address | object | The customer address for the line’s primary place of use. |
| addresLine1 | string | The street address for the line’s primary place of use. This must be a physical address; it cannot be a P.O. box. |
| addresLine2 (optional) | string | Additional address information (Suite number, Office number, etc.) for the line’s primary place of use. |
| city | string | The city for the line’s primary place of use. |
| state | string | The two-letter abbreviation of the state for the line’s primary place of use. To see examples of the two-letter codes (i.e. TX for Texas), please see the Wikipedia page on ISO-3166-2:US. |
| zip | string | The 5-digit ZIP code for the line’s primary place of use. |
| zip4 (optional) | string | The ZIP+4 for the line’s primary place of use. |
| country | string | “US” for the country of the line’s primary place of use. |
| customerName | object | The customer name information to be used for line usage taxation. |
| title (optional) | string | An optional title for the customer, such as Mr. or Dr. |
| firstName | string | The customer’s first name. Valid values are any string of up to 20 alphanumeric characters, space, dash, exclamation point and pound sign. |
| middleName (optional) | string | The customer’s middle name. |
| lastName | string | The customer’s last name. Valid values are any string of up to 25 alphanumeric characters, space, dash, exclamation point and pound sign. |
| suffix (optional) | string | An optional suffix for the customer name, such as Jr. or III. |
| currentServicePlan (optional) | string | This is the service plan value that the device will be switched from. Declaring this value will include all records with the matching currentServicePlan. Leaving this value out will include all records. Note: If the currentServicePlan value doesn't match any existing record, the request will fail. |
Request Body
Example Request (Single Device)
{
"accountName":"0000123456-00001",
"servicePlan":"Name of the plan being changed to",
"deviceListWithServiceAddress":[
{
"deviceIds":[
{
"id":"15-digit alphanumeric",
"kind":"imei"
}
],
"primaryPlaceOfUse":{
"address":{
"addressLine1":"address first line",
"addressLine2":"address second line",
"city":"city name",
"state":"2-letter state ID (ISO 3166)",
"country":"2-letter country code (ISO 3166)",
"zip":"12345"
},
"customerName":{
"firstName":"First Name",
"lastName":"Last Name or Surname"
}
}
}
],
"currentServicePlan":"Optional name of the plan being changed from"
}Example Request (Two Devices)
{
"accountName":"0000123456-00001",
"servicePlan":"Name of the plan being changed to",
"deviceListWithServiceAddress":[
{
"deviceIds":[
{
"id":"15-digit alphanumeric",
"kind":"imei"
}
],
"primaryPlaceOfUse":{
"address":{
"addressLine1":"address first line",
"addressLine2":"address second line",
"city":"city name",
"state":"2-letter state ID (ISO 3166)",
"country":"2-letter country code (ISO 3166)",
"zip":"12345"
},
"customerName":{
"firstName":"First Name",
"lastName":"Last Name or Surname"
}
}
},
{
"deviceIds":[
{
"id":"15-digit alphanumeric",
"kind":"imei"
}
],
"primaryPlaceOfUse":{
"address":{
"addressLine1":"address first line",
"addressLine2":"address second line",
"city":"city name",
"state":"2-letter state ID (ISO 3166)",
"country":"2-letter country code (ISO 3166)",
"zip":"12345"
},
"customerName":{
"firstName":"First Name",
"lastName":"Last Name or Surname"
}
}
}
],
"currentServicePlan":"Optional name of the plan being changed from"
}Success Response
Status 200
{
"requestId": "be36accb-eeee-ffff-gggg-0af6c4ed256a"
}Failure Responses
All error messages are returned in this format:
{
"errorCode": "error code string",
"errorMessage": "error message string"
}Callback Response
{
"username":"user name making the request",
"password":"password of the user",
"requestId":"be36accb-eeee-ffff-gggg-0af6c4ed256a",
"deviceIds":[
{
"id":"10-digit phone number",
"kind":"mdn"
}
],
"deviceResponse":{
"changeServicePlanResponse":{
"effectiveDate":"9/17/2024 12:00:00 AM"
}
}
}Callback Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
| username | string | The user name making the callback request. |
| password | string | The password of the user. |
| requestId | string | The request ID that the callback is for. This is a unique string (UUID) that associates the request with the information that is sent via a callback service. |
| deviceIds | array | An array of device identifier objects where the kind can be imei, imsi, *msisdn, iccid, mdn and min and the id is the value of the kind represented. |
| deviceResponse | object | The object containing the device's response. |
| changeServicePlanResponse | object | An object showing the device response to a plan change. |
| effectiveDate | string | If the change succeeds, this is the timestamp of when the change is effective. |