Thingstream provides a rich Customer API to allow you to carry out the majority of functions that can be done in the portal in addition to providing the ability to report usage on your S2S devices.
The S2S Usage API accepts an array of records to allow reporting for multiple devices or multiple periods.
Single Device Usage
Sample Format for Customer API Post payload:
{
"records": [
{
"periodStart": "yyyy-mm-ddThh:mm:ss.sssZ",
"periodEnd": "yyyy-mm-ddThh:mm:ss.sssZ",
"billingId": "string",
"count": 0
}
]
}
periodStart: String values. The time portion is optional. Validation is in place to ensure that periodStart precedes periodEnd.
periodEnd: String values. The time portion is optional. Validation is in place to ensure that periodStart precedes periodEnd.
billingId: String values. This value is either the S2S device ID obtained from the Thing details pane in the Things List of the Thingstream Portal, or, if billing is managed via a pooled plan, the purchased plan ID which can be found in the billing section of the Thingstream Portal.
count: Integer values. This value must be greater than 0 to ensure a record is created
Usage example with valid inputs:
Posting usage where the start date precedes the end date, billingId is valid and count is > 0:
{
"records":[
{
"periodStart": "2024-08-23",
"periodEnd": "2024-08-24",
"billingId": "device:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"count": 357
}
]
}
Results in a response code of 204 with no body.
Usage examples where there are errors with the inputs:
Posting usage where the end date precedes the start date:
{
"records":[
{
"periodStart": "2024-08-29",
"periodEnd": "2024-08-27",
"billingId": "device:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"count": 1
}
]
}
Results in a response code of 422 with a body of:
{
"errors": [
"periodEnd must be after periodStart"
]
}
Posting usage where an invalid billingId is supplied:
{
"records":[
{
"periodStart": "2024-08-24",
"periodEnd": "2024-08-25",
"billingId": "identity:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"count": 1
}
]
}
Results in a response code of 403 with a body of:
'InvalidbillingId[<billingId>'] and a description of why the value provided is invalid
Posting usage with a zero count:
{
"records":[
{
"periodStart": "2024-08-24",
"periodEnd": "2024-08-25",
"billingId": "identity:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"count": 0
}
Results in a response code of 422 with a body of:
{
"errors": [
"records[n] count must be greater than or equal to 1"
]
}
The index position in the array of the record in error is provided where the count is invalid i.e. 0
Reporting multiple records
The records are scanned to ensure the bulk action is capable of succeeding. Any single 'record' of usage that is in error due to dates, counts or errors in the deviceId will result in a failure to execute all records.
Posting usage reports for multiple records:
{
"records": [
{
"periodStart": "2024-08-27T10:12:07.589Z",
"periodEnd": "2024-08-28T10:12:07.589Z",
"billingId": "device:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"count": 1
},
{
"periodStart": "2024-08-27T10:12:07.589Z",
"periodEnd": "2024-08-28T10:12:07.589Z",
"billingId": "device:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"count": 1
}
]
}
Still need help?
If you need more help or have any questions, please send an email to services-support@u-blox.com.