# Sim BillingPeriod subresource
{% hint style="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](#billingperiod-types), 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.
{% endhint %}
```bash
https://supersim.api.korewireless.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`.
{% hint style="danger" %}
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.
{% endhint %}
## BillingPeriod types
This section describes the behavior of each type of BillingPeriod as indicated by the BillingPeriod's `period_type`.
### Ready BillingPeriods
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](https://docs.korewireless.com/en-us/api/products/supersim/sim-resource#status-values).
### Active BillingPeriods
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](https://docs.korewireless.com/en-us/api/products/supersim/fleet-resource) 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.
***
## API Authorization
Before you can make requests to this resource, you must have a valid bearer token. Review our API [authorization guide](https://docs.korewireless.com/en-us/developers/api-management/auth) to learn how to generate a token. Here's a curl example on how to define your access token in a header:
{% code overflow="wrap" %}
```bash
curl -L "https://supersim.api.korewireless.com/v1/Sims" -H "Authorization: Bearer "
```
{% endcode %}
{% hint style="warning" %}
The examples below do not show the required `Authorization` header due to a bug. We're working on fixing that. In the meantime, be sure to include that in all of your requests.
{% endhint %}
***
## Read multiple BillingPeriod
{% hint style="danger" %}
As noted above, currently only a Sim's current or most recent BillingPeriod will be returned in the results.
{% endhint %}
## Read multiple BillingPeriod resources
> Retrieve a list of Billing Periods for a Super SIM.
```json
{"openapi":"3.0.1","info":{"title":"KORE - Supersim","version":"1.0.0"},"tags":[{"name":"SupersimV1BillingPeriod"}],"servers":[{"url":"https://supersim.api.korewireless.com"}],"security":[{"OAuth":[]}],"components":{"securitySchemes":{"OAuth":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.korewireless.com/api-services/v1/auth/token","scopes":{}}}}},"schemas":{"supersim.v1.sim.billing_period":{"type":"object","properties":{"sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^HB[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the Billing Period."},"account_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^AC[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the [Account](https://docs.korewireless.com/en-us/v/api/global-resources/iam/account) the Super SIM belongs to."},"sim_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^HS[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the Super SIM the Billing Period belongs to."},"start_time":{"type":"string","format":"date-time","nullable":true,"description":"The start time of the Billing Period specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format."},"end_time":{"type":"string","format":"date-time","nullable":true,"description":"The end time of the Billing Period specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format."},"period_type":{"$ref":"#/components/schemas/billing_period_enum_bp_type"},"date_created":{"type":"string","format":"date-time","nullable":true,"description":"The date and time in GMT when the resource was created specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format."},"date_updated":{"type":"string","format":"date-time","nullable":true,"description":"The date and time in GMT when the resource was last updated specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format."}}},"billing_period_enum_bp_type":{"type":"string","nullable":true,"description":"The type of Billing Period. Can be `ready` or `active`.","enum":["ready","active"]}}},"paths":{"/v1/Sims/{SimSid}/BillingPeriods":{"get":{"summary":"Read multiple BillingPeriod resources","description":"Retrieve a list of Billing Periods for a Super SIM.","tags":["SupersimV1BillingPeriod"],"parameters":[{"name":"SimSid","in":"path","description":"The SID of the Super SIM to list Billing Periods for.","schema":{"type":"string"},"required":true},{"name":"PageSize","in":"query","description":"How many resources to return in each list page. The default is 50, and the maximum is 1000.","schema":{"type":"integer","minimum":1,"maximum":1000}},{"name":"Page","in":"query","description":"The page index. This value is simply for client state.","schema":{"type":"integer","minimum":0}},{"name":"PageToken","in":"query","description":"The page token. This is provided by the API.","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"billing_periods":{"type":"array","items":{"$ref":"#/components/schemas/supersim.v1.sim.billing_period"}},"meta":{"properties":{"first_page_url":{"format":"uri","type":"string"},"key":{"type":"string"},"next_page_url":{"format":"uri","nullable":true,"type":"string"},"page":{"type":"integer"},"page_size":{"type":"integer"},"previous_page_url":{"format":"uri","nullable":true,"type":"string"},"url":{"format":"uri","type":"string"}},"type":"object"}},"title":"ListBillingPeriodResponse"}}},"headers":{"Access-Control-Allow-Origin":{"description":"Specify the origin(s) allowed to access the resource","schema":{"type":"string"}},"Access-Control-Allow-Methods":{"description":"Specify the HTTP methods allowed when accessing the resource","schema":{"type":"string"}},"Access-Control-Allow-Headers":{"description":"Specify the headers allowed when accessing the resource","schema":{"type":"string"}},"Access-Control-Allow-Credentials":{"description":"Indicates whether the browser should include credentials","schema":{"type":"boolean"}},"Access-Control-Expose-Headers":{"description":"Headers exposed to the client","schema":{"type":"string"}}},"description":"OK"}},"operationId":"ListBillingPeriod"}}}}
```
***
## How to check if a SIM has hit its data limit
As indicated above, the Sim's current active BillingPeriod is used to determine whether a SIM has exceeded its data limit. A SIM will be blocked if it has used more data between the BillingPeriod's `start_time` and `end_time` than permitted by the Sim's Fleet. To determine what percentage of a SIM's data limit has been used, follow these steps:
1. Fetch the Sim's [Fleet](https://docs.korewireless.com/en-us/api/products/supersim/fleet-resource) using the value from the Sim's `fleet_sid`.
2. Extract the `data_limit` value.
3. Fetch the Sim's current active BillingPeriod.
4. Use the current active BillingPeriod's `start_time` and `end_time` values along with the Sim's SID to query the [UsageRecords](https://docs.korewireless.com/en-us/api/products/supersim/usage-record-resource) resource. If you didn't provide a value for the `Granularity` query parameter, you will only receive one record in the results. This represents the aggregated usage over the request period.
5. Extract the `data_total` value.
6. Divide `data_total` by the Fleet's `data_limit` to determine what percentage of the SIM's data limit has been used.
{% hint style="info" %}
The workflow described above works well if you are building a task applied to a single SIM or to a small number of SIMs that can be iterated over, such as rendering an internal dashboard showing SIM details. However, if you are building a task that will continuously check whether each SIM in your fleet of devices has exceeded its data limit, consider using [Super SIM Connection Events](https://docs.korewireless.com/en-us/developers/event-streams). The `data_modifier` property in [Data Session Started](https://docs.korewireless.com/en-us/developers/event-streams/events#available-events), [Data Session Updated](https://docs.korewireless.com/en-us/developers/event-streams/events#available-events), and [Data Session Ended](https://docs.korewireless.com/en-us/developers/event-streams/events#available-events) events will be populated with `blocked` if a SIM has exceeded its data limit and is being blocked.
{% endhint %}