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.

Loading Code Sample...
      
      
          
          
          
          
        
      Example

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

      Loading Code Sample...
          
          
              
              
              
              
            

          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.

          Loading Code Sample...
              
              
                  
                  
                  
                  
                

              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.

              Loading Code Sample...
                  
                  
                      
                      
                      
                      
                    

                  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.

                  Loading Code Sample...
                      
                      
                          
                          
                          
                          
                        

                      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.

                      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.

                      Loading Code Sample...