Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

REST API: Rate Plans

A Rate Plan describes the capabilities and restrictions of each and every SIM associated with it.

Multiple SIMs can be configured to use the same Rate Plan, meaning that those SIMs inherit the same capabilities and restrictions. However, each SIM's usage is measured independently against the Rate Plan and any limits specified by the Rate Plan are measured and enforced at the individual SIM level. For example, if a Rate Plan specifies a Data Limit of 5MB, every SIM on that Rate Plan will be allowed to consume 5MB of data.

Currently, your ability to edit a Rate Plan once it's created are limited. To change a SIM's capabilities after it's been activated, you'll need to associate it with a different Rate Plan.

Common Tasks

HTTP Resources and Methods

Rate Plan Instance Resource

Resource URLs

https://wireless.twilio.com/v1/RatePlans/{RatePlanSid}
https://wireless.twilio.com/v1/RatePlans/{RatePlanUniqueName}

Resource Properties

A Rate Plan instance resource is represented by the following properties:

Property Type Description
sid String A 34 character string that uniquely identifies this resource.
unique_name String A user-provided string that uniquely identifies this resource as an alternative to the sid.
friendly_name String A user-provided string that identifies this resource. Non-unique.
data_enabled Boolean Defines whether SIMs are capable of using GPRS/3G/4G/LTE data connectivity.
data_limit Integer Network-enforced limit specifying the total Megabytes of data usage (download and upload combined) allowed during one month on the home network. Metering begins on the day of activation and ends on the same day of the following month. Max value is 2TB.
data_metering Enum The model by which to meter data usage, in accordance with the two available data metering models. Valid options are payg, quota-1, quota-10, quota-50.
national_roaming_enabled Boolean Defines whether SIMs can roam onto other networks in the SIM's home country. See 'national' roaming.
national_roaming_data_limit Integer Network-enforced limit specifying the total Megabytes of national roaming data usage (download and upload combined) allowed during one month. Max value is 2TB.
international_roaming_data_limit Integer Network-enforced limit specifying the total Megabytes of national roaming data usage (download and upload combined) allowed during one month. Max value is 2TB.
international_roaming Enum Defines whether SIMs are capable of using GPRS/3G/4G/LTE data connectivity and messaging outside of the United States. Acceptable values are data and messaging.
voice_enabled Boolean Defines whether SIMs are capable of making and receiving voice calls.
messaging_enabled Boolean Defines whether SIMs are capable of making and sending and receiving SMS via Commands.
date_created DateTime The date that this resource was created, given as GMT in ISO 8601 format.
date_updated DateTime The date that this resource was last updated, given as GMT in ISO 8601 format.
account_sid String The unique id of the Account that this Rate Plan belongs to.
url String The URL for this resource.
Explanation of PAYG vs Quota

For low usage devices, the "Pay as you go" (PAYG) Data Metering plan is provided. With PAYG data, you'll only pay for the data you consume, with no minimum data spend per SIM per month.

For higher usage devices, it is probably more cost effective to use a Quota-based Data Metering plan. With a Quota-based plan, you agree to a minimum data spend, or "Quota" level per SIM per month. In return, you will receive discount rates in every country, with more significant discounts for higher Quotas.

Even on a Quota plan, data is still priced per megabyte and metered at byte-level. But at the end of your SIM's billing month, you either pay for exactly what you consumed, or the Quota price, whichever is higher.

See Pricing for more information.

HTTP GET

Returns a representation of the Rate Plan identified by the Sid or UniqueName property.

Example

Request a Rate Plan instance using its Sid, represented as JSON.

        
        
        
        
        Example

        Request a Rate Plan instance using its Unique Name, represented as JSON.

              
              
              
              

              HTTP POST

              The POST method allows you to update a Rate Plan instance resource.

              Optional Parameters

              Any or all of the following parameters can be provided. In the case where a request parameter corresponds to a property on the instance resource, that property will be updated to the provided value.

              Parameter Description
              UniqueName A user-provided string that uniquely identifies this resource as an alternative to the Sid.
              FriendlyName A user-provided string that identifies this resource. Non-unique.

              HTTP PUT

              Not supported.

              HTTP DELETE

              The DELETE method allows you to delete a Rate Plan instance resource.

              Note that Rate Plans can only be deleted when they have no active SIMs associated with them.

              If the Rate Plan is successfully deleted, the API will return an HTTP 204 NO CONTENT response.

                    
                    
                    
                    

                    Rate Plans List Resource

                    Resource URL

                    https://wireless.twilio.com/v1/RatePlans
                    

                    HTTP GET

                    Returns a list of Rate Plans within an account. The list includes paging information.

                    Example 1

                    List all Rate Plans in the account.

                          
                          
                          
                          

                          HTTP POST

                          You can create a new Rate Plan resource by POSTing to the Rate Plans list resource.

                          Required Parameters

                          No required parameters.

                          Optional Parameters

                          Any or all of the following parameters can be provided. In the case where a request parameter corresponds to a property on the instance resource, that property will be set to the provided value. Default values for newly created instance resources are included in the table.

                          Parameter Description Default Property Value
                          UniqueName A user-provided string that uniquely identifies this resource as an alternative to the Sid. null
                          FriendlyName A user-provided string that identifies this resource. Non-unique. null
                          DataEnabled Boolean Defines whether SIMs are capable of using GPRS/3G/LTE data connectivity.
                          DataLimit Integer Network-enforced limit specifying the total Megabytes of data usage (download and upload combined) allowed during one month on the home network. Metering begins on the day of activation and ends on the same day of the following month. Max value is 2TB.
                          DataMetering Enum The model by which to meter data usage, in accordance with the two available data metering models. Valid options are payg, quota-1, quota-10, quota-50.
                          VoiceEnabled Boolean Defines whether SIMs are capable of making and receiving voice calls.
                          MessagingEnabled Boolean Defines whether SIMs are capable of making and sending and receiving SMS messages via either Commands or Programmable SMS APIs.
                          NationalRoamingEnabled Boolean Defines whether SIMs can roam onto other networks in the SIM's home country. See 'national' roaming.
                          NationalRoamingDataLimit Integer Network-enforced limit specifying the total Megabytes of national roaming data usage (download and upload combined) allowed during one month. Max value is 2TB. If unspecified, the default value is the lesser of DataLimit and 1000MB.
                          InternationalRoamingDataLimit Integer Network-enforced limit specifying the total Megabytes of national roaming data usage (download and upload combined) allowed during one month. Max value is 2TB. If unspecified, the default value is the lesser of DataLimit and 1000MB.
                          InternationalRoaming Enum Defines whether SIMs are capable of using GPRS/3G/4G/LTE data connectivity and messaging outside of the United States. Acceptable values are data and messaging.
                          Example

                          Create a new Rate Plan with an UniqueName of 'SmartMeterCA' and a Friendly Name of "California SmartMeter Plan" with a data usage limit of 5MB per month and messaging enabled for Commands.

                                
                                
                                
                                

                                HTTP PUT

                                Not supported.

                                HTTP DELETE

                                Not supported.

                                National Roaming

                                National roaming grants a SIM the ability to roam onto other domestic carrier networks in certain low coverage situations. This will allow a SIM to roam onto regional US networks like GCI in Alaska.

                                National roaming pricing is different to standard data and Commands pricing. Before enabling national roaming on your Rate Plan, it is recommended to review the pricing.

                                Rate this page:

                                Need some help?

                                We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.