POST /licenses/{account}/cancelCreates a list of devices from which licenses will be removed if the number of MRC licenses becomes less than the number of assigned licenses. This can happen when the subscription is changed to a lower number of licenses.
Note: This request is only used with accounts that have a monthly recurring charge (MRC) subscription. Accounts with event-based billing do not need to track licenses.
See also:
Retrieve list of cancellation candidate devices
Delete cancellation candidate List
Nothing is changed for these devices when they are added to the list, or if the number of MRC licenses stays the same or increases. If the number of subscribed licenses is reduced to where it is less than the number of assigned licenses, ThingSpace will remove licenses from as many devices as needed to match the subscribed amount, starting with the first devices in the list. If more licenses need to be removed than the number of devices in this list, ThingSpace will also remove licenses from devices that are not on this list, starting with the first licenses assigned (FIFO).
If an upgrade has started for any devices in the list when the number of subscribed licenses is reduced, the upgrade will complete and the account will be billed for those licenses for another month. If an upgrade is scheduled but has not started, the upgrade will be cancelled.
To remove devices from the cancellation candidate list, send a request that does not include those devices and that does not include type = append. The list of devices in that request will replace the current list.
POST https://thingspace.verizon.com/api/fota/v1/licenses/{account}/cancel
You must include the account name in the path.
| Parameter Name | Data Type | Description |
|---|---|---|
| account required |
string | The name of the account for which you want to create a cancellation candidate list. An account name is usually numeric, and must include any leading zeros. |
The request header must contain a current ThingSpace authorization token and a current VZ-M2M session token, and must set the Content-Type to JSON.
| Parameter Name | Data Type | Description |
|---|---|---|
| Authorization required |
string | HTTP Authorization request header containing a valid 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. |
The request body identifies the devices to include in the list.
| Parameter Name | Data Type | Description |
|---|---|---|
| type optional |
string | Set to “append” to append the devices in the current request to the existing list. If there is no existing list then it will be created with only these devices. Leave this parameter out when you want to replace the existing list with the devices in the current request. |
| deviceList required |
array of IMEI strings | The IMEIs of the devices to add to the list. |
Add two devices to the existing cancellation candidate list:
curl https://thingspace.verizon.com/api/fota/v1/licenses/$ACCOUNT/cancel -H 'Authorization: Bearer $AUTH_TOKEN' -H 'VZ-M2M-Token: $M2M_TOKEN' -H 'Content-Type: application/json' -d
{
"type": "append",
"deviceList": [
"990003425730535",
"990000473475989"
]
}
Status 200
A success response includes the total number of devices on the list and the IMEIs of those devices.
| Parameter Name | Data Type | Description |
|---|---|---|
| count | integer | The total number of devices on the cancellation candidate list. |
| deviceList | array of IMEI strings | The IMEIs of the devices on the cancellation candidate list. |
{
"count": 2,
"deviceList": [
"900000000000001",
"900000000000999"
]
}
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.