Documentation

Mistake on this page? Email us

Billing API

The Billing API allows commercial users to retrieve billing reports and service package details.

Billing report:

Billing reports for the previous month are generated automatically during the third business day of the current month. The reports are usually available by 02:00 AM UTC.

Service package:

If you have a commercial account, you can create a service package with a specific number of firmware updates, referred to as the service package quota. You can only perform device updates equal to the number of firmware updates linked to an active service package. You must purchase a new service package or renew an active one if you have reached the quota for your active service package.

Aggregator customers share their service package quota with their own subtenant accounts. A subtenant can create campaigns utilizing the parent account's service package quota. A subtenant cannot create or manage service packages on its own. The quota usage history is recorded separately between the aggregator and subtenants.

Service package events:

The following service package events are included in API responses:

reservation:

Creation of a new update campaign with an estimated number of firmware updates.

reservation_release:

Closing an update campaign. The unused quota reserved through the update campaign is added to the active service package quota at this point.

reservation_termination:

Termination of an update campaign due to the expiration of an active service package. The unused quota reserved through the update campaign cannot be used if the active service package has expired.

package_creation:

Creation of a new service package.

package_renewal:

Renewal of an active service package before it expires.

package_termination:

Expiration of an active service package. The unused quota linked to the expired service package cannot be used anymore.

Version: 2.0.0
Host: http://api.us-east-1.mbedcloud.com

Endpoints

Default

get /v3/billing-report
Get billing report. Show more Show less

Fetch the billing report generated for the currently authenticated commercial non-subtenant account. Billing reports for subtenant accounts are included in their aggregator's billing report response.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/billing-report?month=2018-07 \
-H 'Authorization: Bearer <api_key>'
Query parameters
month (required)
Query Parameter — Queried year and month of billing report.
Return type
Example data
Content-Type: application/json
{
  "id" : "6cae0aec221911e88f227f51b2f005c0",
  "object" : "billing-report",
  "account" : {
    "address_line1" : null,
    "address_line2" : null,
    "city" : null,
    "company" : "example-company",
    "contact" : null,
    "country" : null,
    "email" : null,
    "id" : "example-account",
    "phone_number" : null,
    "postal_code" : null,
    "state" : null
  },
  "aggregated" : {
    "active_devices" : 600,
    "firmware_updates" : 600,
    "sda_tokens" : 700,
    "generated" : "2016-09-21T14:11:34.131Z",
    "period_end" : "2016-09-30T23:59:59.999Z",
    "period_start" : "2016-09-01T00:00.000Z"
  },
  "billing_data" : {
    "active_devices" : 100,
    "firmware_updates" : 100,
    "sda_tokens" : 200,
    "generated" : "2016-09-21T14:11:34.131Z",
    "period_end" : "2016-09-30T23:59:59.999Z",
    "period_start" : "2016-09-01T00:00.000Z"
  },
  "month" : "2016-09",
  "service_package" : {
    "metadata" : {
      "end_time" : null,
      "remaining_quota" : 1000,
      "reserved_quota" : 100,
      "start_time" : "2016-09-01T00:00.000Z"
    },
    "quota_usage" : [ {
      "amount" : 1000,
      "campaign_name" : null,
      "time" : "2016-09-01T00:00.000Z",
      "type" : "package_creation"
    }, {
      "amount" : -50,
      "campaign_name" : "example-account-campaign-name",
      "time" : "2016-09-02T00:00.000Z",
      "type" : "reservation"
    } ],
    "aggregated_quota_usage" : [ {
      "account_id" : "example-account",
      "amount" : 1000,
      "campaign_name" : null,
      "time" : "2016-09-01T00:00.000Z",
      "type" : "package_creation"
    }, {
      "account_id" : "example-account",
      "amount" : -50,
      "campaign_name" : "example-account-campaign-name",
      "time" : "2016-09-02T00:00.000Z",
      "type" : "reservation"
    }, {
      "account_id" : "example-subtenant-account-1",
      "amount" : -20,
      "campaign_name" : "example-subtenant-account-1-campaign-name",
      "time" : "2016-09-03T00:00.000Z",
      "type" : "reservation"
    }, {
      "account_id" : "example-subtenant-account-2",
      "amount" : -30,
      "campaign_name" : "example-subtenant-account-2-campaign-name",
      "type" : "reservation",
      "time" : "2016-09-04T00:00.000Z"
    } ]
  },
  "subtenants" : [ {
    "account" : {
      "address_line1" : null,
      "address_line2" : null,
      "city" : null,
      "company" : "example-subtenant-company-1",
      "contact" : null,
      "country" : null,
      "customer_subtenant_id" : "example-customer-subtenant-id-1",
      "email" : null,
      "id" : "example-subtenant-account-1",
      "phone_number" : null,
      "postal_code" : null,
      "state" : null
    },
    "billing_data" : {
      "active_devices" : 200,
      "firmware_updates" : 200,
      "sda_tokens" : 300,
      "generated" : "2016-09-21T14:11:34.131Z",
      "period_end" : "2016-09-30T23:59:59.999Z",
      "period_start" : "2016-09-01T00:00.000Z"
    },
    "service_package" : {
      "quota_usage" : [ {
        "amount" : -20,
        "campaign_name" : "example-subtenant-account-1-campaign-name",
        "time" : "2016-09-03T00:00.000Z",
        "type" : "reservation"
      } ]
    }
  }, {
    "account" : {
      "address_line1" : null,
      "address_line2" : null,
      "city" : null,
      "company" : "example-subtenant-company-2",
      "contact" : null,
      "country" : null,
      "customer_subtenant_id" : "example-customer-subtenant-id-2",
      "email" : null,
      "id" : "example-subtenant-account-2",
      "phone_number" : null,
      "postal_code" : null,
      "state" : null
    },
    "billing_data" : {
      "active_devices" : 300,
      "firmware_updates" : 300,
      "sda_tokens" : 200,
      "generated" : "2016-09-21T14:11:34.131Z",
      "period_end" : "2016-09-30T23:59:59.999Z",
      "period_start" : "2016-09-01T00:00.000Z"
    },
    "service_package" : {
      "quota_usage" : [ {
        "amount" : -30,
        "campaign_name" : "example-subtenant-account-2-campaign-name",
        "time" : "2016-09-04T00:00.000Z",
        "type" : "reservation"
      } ]
    }
  } ]
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Billing report response object. ReportResponse
400 Bad request. BadRequestErrorResponse
401 Unauthorized access. UnauthorizedErrorResponse
403 Access forbidden if account is not commercial or subtenant. ForbiddenErrorResponse
404 Billing report not found if requested month is current or in the future. Also could not be available for previous months in special cases. ReportNotFoundErrorResponse
500 Internal server error. InternalServerErrorResponse
get /v3/billing-report-active-devices
Get raw billing data of the active devices for the month. Show more Show less

Fetch raw billing data for active devices for the currently authenticated commercial non-subtenant account. This is supplementary data for the billing report. The raw billing data of the active devices for subtenant accounts are included in their aggregator's raw billing data of the active devices.

The endpoint returns the URL to download the gzipped CSV file. The first line is the header providing information on active devices, for example, the ID of an active device.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/billing-report-active-devices?month=2018-07 \
-H 'Authorization: Bearer <api_key>'
Query parameters
month (required)
Query Parameter — Queried year and month of billing report.
Return type
Example data
Content-Type: application/json
{
  "object" : "billing-report-active-devices",
  "url" : "https://example.com/example.csv.gz",
  "filename" : "example.csv.gz"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 The response includes the URL to download raw billing data of the active devices. BillingReportRawDataResponse
400 Bad request. BadRequestErrorResponse
401 Unauthorized access. UnauthorizedErrorResponse
403 Access forbidden if account is not commercial or subtenant. ForbiddenErrorResponse
404 Active devices billing data not found. ReportNotFoundErrorResponse
500 Internal server error. InternalServerErrorResponse
get /v3/billing-report-firmware-updates
Get raw billing data of the firmware updates for the month. Show more Show less

Fetch raw billing data for firmware updates for the currently authenticated commercial non-subtenant account. This is supplementary data for the billing report. The raw billing data of the firmware updates for subtenant accounts are included in their aggregator's raw billing data of the firmware updates.

The endpoint returns the URL to download the gzipped CSV file. The first line is the header providing information on the firmware updates, for example, the ID of a firmware update.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/billing-report-firmware-updates?month=2018-07 \
-H 'Authorization: Bearer <api_key>'
Query parameters
month (required)
Query Parameter — Queried year and month of billing report.
Return type
Example data
Content-Type: application/json
{
  "object" : "billing-report-firmware-updates",
  "url" : "https://example.com/example.csv.gz",
  "filename" : "example.csv.gz"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 The response includes the URL to download raw billing data of the firmware updates. BillingReportRawDataResponse
400 Bad request. BadRequestErrorResponse
401 Unauthorized access. UnauthorizedErrorResponse
403 Access forbidden if account is not commercial or subtenant. ForbiddenErrorResponse
404 Firmware updates billing data not found. ReportNotFoundErrorResponse
500 Internal server error. InternalServerErrorResponse
get /v3/service-packages-quota
Service package quota. Show more Show less

Get the available firmware update quota for the current authenticated commercial account.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/service-packages-quota \
-H 'Authorization: Bearer <api_key>'
Return type
Example data
Content-Type: application/json
{
  "object" : "service-package-quota",
  "quota" : 1000
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Firmware update quota for the current authenticated commercial account. ServicePackageQuota
401 Unauthorized access. UnauthorizedErrorResponse
403 Forbidden. ForbiddenErrorResponse
500 Internal server error. InternalServerErrorResponse
get /v3/service-packages-quota-history
Service package quota history. Show more Show less

Get your quota usage history. This API is available only for commercial accounts. Aggregator accounts can see their own and subtenant quota usage data. Data is in ascending order based on the added timestamp.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/service-packages-quota-history \
-H 'Authorization: Bearer <api_key>'
Query parameters
limit (optional)
Query Parameter — Maximum number of quota history entries contained in one paged response. format: int32
after (optional)
Query Parameter — Results after specified entry ID.
Return type
Example data
Content-Type: application/json
{
  "after" : null,
  "data" : [ {
    "id" : "787148a58f51434e938f8e0e54c09699",
    "added" : "2017-10-10T10:45:12.896Z",
    "amount" : 20,
    "reason" : "package_creation",
    "reservation" : null,
    "service_package" : {
      "expires" : "2018-10-10T10:45:12.300Z",
      "firmware_update_count" : 20,
      "previous_id" : null,
      "id" : "010c804b945f4c33b2d1e313ed95094e",
      "start_time" : "2017-10-10T10:45:12.300Z"
    }
  }, {
    "id" : "b0817554677248a1b038d7fcd2c020c5",
    "added" : "2017-11-10T13:45:51.273Z",
    "amount" : -1,
    "reason" : "reservation",
    "reservation" : {
      "campaign_name" : "campaign",
      "id" : "b5322aabe29d458ea6e4402594085a15",
      "account_id" : "TEST-commercial.5f1edb5c-c61d-11e7-a05a-00155d004e00"
    },
    "service_package" : null
  } ],
  "has_more" : false,
  "limit" : 50,
  "object" : "service-package-quota-history",
  "total_count" : 2
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Quota history for the currently authenticated commercial account. ServicePackageQuotaHistoryResponse
401 Unauthorized access. UnauthorizedErrorResponse
403 Forbidden. ForbiddenErrorResponse
500 Internal server error. InternalServerErrorResponse
get /v3/service-packages
Get all service packages. Show more Show less

Get information for all service packages for the current authenticated commercial account. The response is returned in descending order by service package created timestamp: first the pending service package, then the active service package, then the previous service packages.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/service-packages \
-H 'Authorization: Bearer <api_key>'
Return type
Example data
Content-Type: application/json
{
  "object" : "service-packages",
  "pending" : {
    "id" : "example-service-package-id-4",
    "previous_id" : "example-service-package-id-3",
    "created" : "2017-03-01T00:00:00.000Z",
    "modified" : "2017-03-01T00:00:00.000Z",
    "start_time" : "2018-01-01T00:00:00.000Z",
    "expires" : "2019-01-01T00:00:00.000Z",
    "firmware_update_count" : 400000
  },
  "active" : {
    "id" : "example-service-package-id-3",
    "previous_id" : "example-service-package-id-2",
    "next_id" : "example-service-package-id-4",
    "created" : "2017-01-01T00:00:00.000Z",
    "modified" : "2017-01-01T00:00:00.000Z",
    "start_time" : "2017-01-01T00:00:00.000Z",
    "expires" : "2018-01-01T00:00:00.000Z",
    "firmware_update_count" : 300000,
    "grace_perid" : false
  },
  "previous" : [ {
    "id" : "example-service-package-id-2",
    "previous_id" : "example-service-package-id-3",
    "next_id" : "example-service-package-id-3",
    "created" : "2016-01-01T00:00:00.000Z",
    "modified" : "2017-02-01T00:00:00.000Z",
    "start_time" : "2016-01-01T00:00:00.000Z",
    "expires" : "2017-01-01T00:00:00.000Z",
    "end_time" : "2017-02-01T00:00:00.000Z",
    "firmware_update_count" : 200000,
    "reason" : "renewed"
  }, {
    "id" : "example-service-package-id-1",
    "previous_id" : null,
    "next_id" : "example-service-package-id-2",
    "created" : "2015-01-01T00:00:00.000Z",
    "modified" : "2016-02-01T00:00:00.000Z",
    "start_time" : "2015-01-01T00:00:00.000Z",
    "expires" : "2016-01-01T00:00:00.000Z",
    "end_time" : "2016-02-01T00:00:00.000Z",
    "firmware_update_count" : 100000,
    "reason" : "renewed"
  } ]
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Information for all service packages associated with an account. ServicePackagesResponse
401 Unauthorized access. UnauthorizedErrorResponse
403 Forbidden. ForbiddenErrorResponse
500 Internal server error. InternalServerErrorResponse

Models

ActiveServicePackage

An active service package.
id
String ID of this service package.
previous_id (optional)
String Previous service package ID or null.
next_id (optional)
String Next service package ID if this service package has a pending renewal, or null.
created
Date Service package creation time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
modified
Date Service package latest modified time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
start_time
Date Service package start time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
expires
Date Service package expiration time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
firmware_update_count
Integer Size of firmware update quota of this service package. format: int32
grace_period
Boolean Indicates whether the service package is in its grace period.

AggregatedQuotaUsageReport

Aggregated quota usage entry.
account_id
amount
Long Amount of quota usage entry. Negative if quota consumption. format: int64
type
String Type of quota usage entry.
Enum:
reservation
reservation_release
reservation_termination
package_renewal
package_creation
package_termination
time
Date Added time of quota usage entry in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
campaign_name (optional)
String Campaign name of quota usage entry. Null if quota usage entry type is not reservation or reservation release.

BadRequestErrorResponse

400 Bad request response.
object
String Always set to error.
Enum:
error
message
String A human-readable message with detailed info.
request_id
String Request ID.
type
String Error type. Always set to validation_error.
Enum:
validation_error
code
Integer Response code. Always set to 400.
fields

BadRequestErrorResponseField

Single field that failed validation.
name
String Name of the field that failed validation. If name is set to body, then the validation failed on request body.
message
String A human-readable message with detailed validation error.

BillingReportRawDataResponse

The response includes the URL to download raw billing data.
object
String API Resource name.
url
String The URL to download raw billing data.
filename
String The filename of the raw billing data file to download. Contains file extensions.

ForbiddenErrorResponse

403 Forbidden.
object
String Always set to error.
Enum:
error
message
String A human-readable message with detailed info.
request_id
String Request ID
type
String Error type. Always set to forbidden.
Enum:
forbidden
code
Integer Response code. Always set to 403.

InternalServerErrorResponse

500 Internal server error response.
object
String Always set to error.
Enum:
error
message
String A human-readable message with detailed info.
request_id
String Request ID
type
String Error type. Always set to internal_error.
Enum:
internal_error
code
Integer Response code. Always set to 500.

PendingServicePackage

A pending service package.
id
String ID of this service package.
previous_id
String Previous service package ID.
created
Date Service package creation time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
modified
Date Service package latest modified time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
start_time
Date Service package start time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
expires
Date Service package expiration time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
firmware_update_count
Integer Size of firmware update quota of this service package. format: int32

PreviousServicePackage

Previously active service package.
id
String ID of this service package.
previous_id (optional)
String Previous service package ID.
next_id (optional)
String Next service package ID if this service package has a pending renewal or null.
created
Date Service package creation time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
modified
Date Service package latest modified time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
start_time
Date Service package start time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
expires
Date Service package expiration time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
end_time
Date Service package end time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
firmware_update_count
Integer Size of firmware update quota of this service package. format: int32
reason
String Reason the service package was ended.
Enum:
renewed
terminated

QuotaUsageReport

Account quota usage entry for queried month.
amount
Long Amount of quota usage entry. Negative if quota consumption. format: int64
type
String Type of quota usage entry.
Enum:
reservation
reservation_release
reservation_termination
package_renewal
package_creation
package_termination
time
Date Added time of quota usage entry in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
campaign_name (optional)
String Campaign name of quota usage entry. Null if quota usage entry type is not reservation or reservation release.

ReportAccountContactInfo

Account contact information.
id
String Account ID.
company
contact (optional)
email (optional)
phone_number (optional)
address_line1 (optional)
address_line2 (optional)
postal_code (optional)
city (optional)
state (optional)
country (optional)

ReportBillingData

generated
Date Billing report generated time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
period_start
Date Billing report start time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
period_end
Date Billing report end time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
active_devices
Long format: int64
firmware_updates
Long format: int64
sda_tokens
Long format: int64

ReportNotFoundErrorResponse

404 Not found response.
object
String Always set to error.
Enum:
error
message
String A human-readable message with detailed info.
request_id
String Request ID
type
String Error type. Always set to report_not_found.
Enum:
report_not_found
code
Integer Response code. Always set to 404.

ReportResponse

Billing report response.
id
String Billing report ID.
object
String Billing report response object. Always set to billing-report.
Enum:
billing-report
account
ReportAccountContactInfo Account contact information.
billing_data
ReportBillingData Report billing data.
subtenants
array[SubtenantAccountReport] List of billing reports for subtenant accounts. Empty list if account does not have any subtenant account.
aggregated
ReportBillingData Aggregated report billing data including all subtenant accounts, if any.
service_package (optional)
ServicePackageReport Report service package.
month
String Month of requested billing report.

ServicePackageMetadata

Account's service package metadata. Value is null if service package has expired.
start_time
Date Service package start time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
end_time
Date Service package end time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
remaining_quota
Long Current available service package quota. format: int64
reserved_quota
Long Sum of all open reservations for this account. format: int64

ServicePackageQuota

Quota of the service package.
object
String Always set to service-package-quota.
Enum:
service-package-quota
quota
Long Available quota for the service package. format: int64

ServicePackageQuotaHistoryItem

Quota history item.
id
String Service package quota history ID.
added
Date Added time of quota history entry in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
amount
Long Negative or positive quota usage. format: int64
reason
String Type of quota usage entry.
Enum:
reservation
reservation_release
reservation_termination
package_creation
package_renewal
package_termination
reservation (optional)
ServicePackageQuotaHistoryReservation Reservation details if reason is reservation, reservation_releasem or reservation_termination.
service_package (optional)
ServicePackageQuotaHistoryServicePackage Service package details if reason is package_creation, package_renewal or package_termination.

ServicePackageQuotaHistoryReservation

Service package quota history reservation object.
id
String Reservation ID.
account_id
String Account ID.
campaign_name
String Campaign name for this reservation.

ServicePackageQuotaHistoryResponse

Quota history of the service package.
object
String Always set to service-package-quota-history.
Enum:
service-package-quota-history
data
array[ServicePackageQuotaHistoryItem] List of history items. Empty list if no entries are available.
has_more
Boolean If there is next available quota history paged response to fetch.
limit
Integer Maximum number of quota history entries contained in one paged response. format: int32
total_count
Integer Sum of all quota history entries that should be returned. format: int32
after (optional)
String ID after which to fetch quota history.

ServicePackageQuotaHistoryServicePackage

Service package quota history service package object.
id
String ID of this service package.
previous_id (optional)
String Previous service package ID, or null.
start_time
Date Service package start time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
expires
Date Service package expiration time in RFC3339 date-time with millisecond accuracy and UTC time zone. format: date-time
firmware_update_count
Integer Size of firmware update quota of this service package. format: int32

ServicePackageReport

Account's current service package data included in reporting.
metadata
ServicePackageMetadata Null if service package has expired.
quota_usage
aggregated_quota_usage

ServicePackagesResponse

Contains service package information for currently active service package, currently pending service package, and all previous service packages associated with the account.
object
String Always set to service-packages.
Enum:
service-packages
pending (optional)
PendingServicePackage Current pending service package. Can be null.
active (optional)
ActiveServicePackage Currently active service package. Can be null.
previous
array[PreviousServicePackage] List of previous service packages.

SubtenantAccountReport

Billing report for subtenant account.
account
SubtenantReportAccountContactInfo Subtenant account contact information.
billing_data
ReportBillingData Report billing data.
service_package (optional)
SubtenantServicePackageReport Report service package for subtenant account.

SubtenantReportAccountContactInfo

Subtenant account contact information.
id
String Account ID.
company
contact (optional)
email (optional)
phone_number (optional)
address_line1 (optional)
address_line2 (optional)
postal_code (optional)
city (optional)
state (optional)
country (optional)
customer_subtenant_id
String Account subtenant ID, if a subtenant.

SubtenantServicePackageReport

UnauthorizedErrorResponse

401 Unauthorized response.
object
String Always set to error.
Enum:
error
message
String A human-readable message with detailed info.
request_id
String Request ID
type
String Error type. Always set to unauthorized.
Enum:
unauthorized
code
Integer Response code. Always set to 401.