Customer API - Switch Plan
Thingstream provides a rich Customer API to allow you to carry out the majority of functions that can be done in the portal like changing the status of a Thing, or swapping to a different connectivity plan.
Here we are going to provide a guide to switching plans on one or more "Things".
You'll find the API documentation for switching plan on Swagger. The access key and secret required for authentication can be found by selecting "Show Access Keys" under Settings/Domain Settings
In this section
Still need help?
If you need more help or have any questions, please send an email to services-support@u-blox.com
The switchPlan endpoint provides a mechanism for switching the plan on one or more "Things" either immediately of on the anniversary of the plan.
Below is an example of the default request payload:
{
"ids": [
"string"
],
"toPlanId": "string",
"switchImmediately": true
}
Switching the plan requires:
the identity of one or more "Things" ("ids")
the Identity of the plan you wish to switch the "Things" onto ("toPlanId")
whether to switch plans immediately ("switchImmediately":true) or to schedule the switch for the next anniversary of the plan ("switchImmediately":false)
Obtain the Identity of one or more "Things"
The Customer API provides a powerful search endpoint that makes it simple to obtain the identity of one or more "Things".
A detailed explanation of how to use search to obtain identities is available on the Customer API - Search page.
Obtain the identity of a plan
There are two endpoints that provide a list of plans/tariffs.
/thing/tariffs
/thing/tariffs/<type>
Included in the response to both are full details of each plan/tariff including it's identity. This will be returned as the 'entityId' and can take one of several forms depending on the type of Thing, mostly they will appear as follows:
"entityId": "plan:33xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
or
"entityId": "tariff:33xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
There is no request payload for this endpoint as all plans/tariffs that are applicable to the types of Things that are in your domain wil be returned.
For the endpoint /thing/tariffs/<type>, the type would be one of the following:
THINGSTREAM_SIM, THINGSTREAM_INTERNET, THINGSTREAM_LORA, MQTT_FLEX, CLOUDLOCATE_GNSS, CLOUDLOCATE_S2S, CELLLOCATE_S2S, POINTPERFECT, POINTPERFECT_S2S, RTCM, POINTSAFE
To obtain a list of tariffs/plans available to SIM things in your domain the call would be to
/thing/tariffs/THINGSTREAM_SIM
Swagger provides a dropdown for the various types. If you plan to use the curl statement that is generated for an automated query, you can replace the <type> from the list above.
Switch plan for one or more Things
The request for this endpoint takes one or more 'Thing' identities in the "ids" array, which is a comma separated list of identities ontained by following the instructions in (1).
The 'toPlanId' will be the entity Id of the plan/tariff obtained in (2). You can also opt to switch the plans immediately or on the anniversary of the monthly plan rollover.
The default request payload for the switchPlan endpoint looks as follows:
{
"ids": [
"string"
],
"toPlanId": "string",
"switchImmediately": true
}
An example of an immediate switch would look similar to this
{
"ids": [
"device:7e4exxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
"device:98baxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
],
"toPlanId": "tariff:2655xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"switchImmediately": true
}
to perform the same activity but schedule the plan switch for the next plan anniversary, simply set "switchImmediately" to false
{
"ids": [
"device:7e4exxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
"device:98baxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
],
"toPlanId": "tariff:2655xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"switchImmediately": false
}