Create Cancellation Candidate List

Create a Cancellation Candidate List:
POST /licenses/{account}/cancel

Creates 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.

Contents

See also:
Retrieve list of cancellation candidate devices
Delete cancellation candidate List

Uses and Requirements

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.

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/fota/v1/licenses/{account}/cancel

Resource Path and Query Parameters

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.

Header Parameters

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.

Request Body

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.

Example Request

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"
  ]
}

Success Responses

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"
  ]
}

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.