Skip to contentSkip to navigationSkip to topbar
Rate this Page:

BillingPeriod Subresource


(warning)

Warning

Super SIM's Billing Periods API is currently in Public Beta . Some features are not yet implemented and others may be changed before the product is declared Generally Available. Beta products are not covered by a Twilio SLA*.* Learn more about beta product support(link takes you to an external page).

(information)

Info

To avoid ambiguity throughout this page, Sim (initial cap) refers to the Sim API resource. SIM (all caps) refers to the physical Subscriber Identity Module (that is, a SIM card) associated with a Sim resource.

A BillingPeriod instance represents a period of time and belongs to a Sim instance. Depending on the type of the BillingPeriod, billing events such as charging a SIM's monthly subscription fee or resetting the amount applied towards a SIM's data limit may occur at the start or the end of a BillingPeriod.


_10
https://supersim.twilio.com/v1/Sims/{sid}/BillingPeriods

A Sim whose status is new will not have any BillingPeriods. A Sim's first BillingPeriod will be created when its status is updated to ready or active and will begin at the time denoted by the BillingPeriod's start_time. Events set to occur at the start of the BillingPeriod will take place. When a BillingPeriod expires — i.e., the current time is after the BillingPeriod's end_time — any events set to occur at the end of the BillingPeriod will take place. Unless the Sim's status is inactive, when its BillingPeriod expires a new one will be created. This process will be repeated for as long as the Sim's status continues to be active.

(warning)

Warning

Currently, only a Sim's current or most recent BillingPeriod will be returned when reading a Sim's BillingPeriods. It will be returned as a single result in an array. In a future release, we will add the ability to view previous BillingPeriods as a paginated list.


BillingPeriod Properties

billingperiod-properties page anchor
Resource properties
sidtype: SID<HB>

The SID of the Billing Period.


account_sidtype: SID<AC>

The SID of the Account(link takes you to an external page) the Super SIM belongs to.


sim_sidtype: SID<HS>

The SID of the Super SIM the Billing Period belongs to.


start_timetype: string<DATE TIME>

The start time of the Billing Period specified in ISO 8601(link takes you to an external page) format.


end_timetype: string<DATE TIME>

The end time of the Billing Period specified in ISO 8601(link takes you to an external page) format.


period_typetype: enum<STRING>

The type of Billing Period. Can be ready or active.

Possible values:
readyactive

date_createdtype: string<DATE TIME>

The date and time in GMT when the resource was created specified in ISO 8601(link takes you to an external page) format.


date_updatedtype: string<DATE TIME>

The date and time in GMT when the resource was last updated specified in ISO 8601(link takes you to an external page) format.


This section describes the behavior of each type of BillingPeriod as indicated by the BillingPeriod's period_type.

Ready BillingPeriods

ready-billingperiods page anchor

A Sim resource's status can only be updated to ready from new. When this change occurs, a ready BillingPeriod resource will be created starting at that time. The ready BillingPeriod's end_time indicates when the Sim resource's status will automatically transition from ready to active if no other transition criteria are met. When a Sim's status is ready, the SIM it represents may connect to the cellular networks without incurring a monthly subscription fee until either the ready BillingPeriod expires, or some amount of data/SMS Command usage occurs, whichever comes first. Learn more about each Sim resource status.

A new active BillingPeriod will be created in either of these cases:

  • A Sim's status is updated to active and there is not already an unexpired active BillingPeriod for that Sim.
  • An active BillingPeriod expires and the status of the Sim to which it belongs is still active .

When an active BillingPeriod is created, the monthly active SIM subscription fee will be charged. If a Sim's status is updated to inactive before the current active BillingPeriod expires, no new BillingPeriod will be created. If Sim's status is later changed back to active, a new active BillingPeriod will be created starting at that time.

Each SIM has a data limit dictated by the Fleet to which its Sim resource has been assigned. Data usage is counted during the Sim's current active BillingPeriod and compared to the Sim's data limit. If the count reaches the limit, the SIM will be blocked from using any more data until the active BillingPeriod expires. When an active BillingPeriod expires, the data usage counter is reset to zero. If a SIM has been blocked from using data because it exceeded its data limit, it will be able to resume using data at this point.


Read multiple BillingPeriod resources

read-multiple-billingperiod-resources page anchor
GET https://supersim.twilio.com/v1/Sims/{SimSid}/BillingPeriods

(warning)

Warning

As noted above, currently only a Sim's current or most recent BillingPeriod will be returned in the results.

Parameters

list-parameters page anchor
URI parameters
SimSidtype: string
Path Parameter

The SID of the Super SIM to list Billing Periods for.


PageSizetype: integer
Query Parameter

How many resources to return in each list page. The default is 50, and the maximum is 1000.


Pagetype: integer
Query Parameter

The page index. This value is simply for client state.


PageTokentype: string
Query Parameter

The page token. This is provided by the API.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.supersim.v1.sims('HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.billingPeriods
_11
.list({limit: 20})
_11
.then(billingPeriods => billingPeriods.forEach(b => console.log(b.sid)));

Output

_23
{
_23
"billing_periods": [
_23
{
_23
"sid": "HBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"sim_sid": "HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"period_type": "active",
_23
"start_time": "2021-06-09T13:18:15Z",
_23
"end_time": "2021-07-09T13:18:15Z",
_23
"date_created": "2021-06-09T13:18:16Z",
_23
"date_updated": "2021-06-09T13:18:16Z"
_23
}
_23
],
_23
"meta": {
_23
"page": 0,
_23
"page_size": 50,
_23
"first_page_url": "https://supersim.twilio.com/v1/Sims/HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/BillingPeriods?PageSize=50&Page=0",
_23
"previous_page_url": "https://supersim.twilio.com/v1/Sims/HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/BillingPeriods?PageSize=50&Page=0",
_23
"url": "https://supersim.twilio.com/v1/Sims/HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/BillingPeriods?PageSize=50&Page=0",
_23
"next_page_url": "https://supersim.twilio.com/v1/Sims/HSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/BillingPeriods?PageSize=50&Page=1",
_23
"key": "billing_periods"
_23
}
_23
}


Rate this Page: