Menu

Expand
Rate this page:

REST API: UsageTrigger

A UsageTrigger is a webhook that notifies your application of usage thresholds.

Twilio can send your web application an HTTP request when certain events happen, such as an incoming text message to one of your Twilio phone numbers. These requests are called webhooks, or status callbacks. For more, check out our guide to Getting Started with Twilio Webhooks. Find other webhook pages, such as a security guide and an FAQ in the Webhooks section of the docs.

It can take some amount of time for the data used by usage triggers to be reflected in the UsageTriggers evaluations.

Using this resource, you can make or update a new UsageTrigger, fetch information about an existing UsageTrigger or multiple UsageTriggers, or delete an existing UsageTrigger.

You can configure UsageTriggers to recur daily, monthly, or yearly. UsageTriggers are evaluated frequently — about once a minute — to provide timely information to your application.

You can also set UsageTriggers for any usage category. For example, you can create a single UsageTrigger to track daily usage. In this case, a UsageTrigger notifies your application when your cost exceeds a set daily amount. If used together with Subaccounts created for each end-user, then a UsageTrigger would notify your application that a specific user has exceeded an allocated monthly usage.

For more information, see Usage categories in Usage Records as well as Subaccounts.

UsageTrigger properties

A UsageTrigger is represented by the following properties:

Resource Properties in REST API format
account_sid
sid<AC> Not PII

The SID of the Account that the trigger monitors.

api_version
string Not PII

The API version used to create the resource.

callback_method
http_method Not PII

The HTTP method we use to call callback_url. Can be: GET or POST.

callback_url

The URL we call using the callback_method when the trigger fires.

current_value
string Not PII

The current value of the field the trigger is watching.

date_created
date_time<rfc2822> Not PII

The date and time in GMT that the resource was created specified in RFC 2822 format.

date_fired
date_time<rfc2822> Not PII

The date and time in GMT that the trigger was last fired specified in RFC 2822 format.

date_updated
date_time<rfc2822> Not PII

The date and time in GMT that the resource was last updated specified in RFC 2822 format.

friendly_name
string Not PII

The string that you assigned to describe the trigger.

recurring
enum:recurring Not PII

The frequency of a recurring UsageTrigger. Can be: daily, monthly, or yearly for recurring triggers or empty for non-recurring triggers. A trigger will only fire once during each period. Recurring times are in GMT.

sid
sid<UT> Not PII

The unique string that that we created to identify the UsageTrigger resource.

trigger_by
enum:trigger_field Not PII

The field in the UsageRecord resource that fires the trigger. Can be: count, usage, or price, as described in the UsageRecords documentation.

trigger_value
string Not PII

The value at which the trigger will fire. Must be a positive, numeric value.

uri
uri Not PII

The URI of the resource, relative to https://api.twilio.com.

usage_category
enum:usage_category Not PII

The usage category the trigger watches. Must be one of the supported usage categories.

usage_record_uri
string Not PII

The URI of the UsageRecord resource this trigger watches, relative to https://api.twilio.com.

CallbackUrl requests

When an account's usage category crosses a UsageTrigger's TriggerValue during the specified interval, then Twilio makes a request to the CallbackUrl using the HTTP method CallbackMethod with the CallbackUrl Request parameters.

Twilio guarantees that a UsageTrigger will fire once (at most) during its recurring interval and will quickly retry the callback URL three times after a 5xx error.

For more information, see CallbackUrl Request Parameters below.

Create a UsageTrigger Resource

post
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Triggers.json

Each account can create up to 1,000 UsageTriggers. If UsageTrigger creation is successful, Twilio will respond with a representation of the new trigger.

Inactive UsageTriggers will not be deleted automatically.

You need to delete triggers you no longer need. For more information, see Delete a UsageTrigger resource below.

Parameters
Parameters in REST API format
account_sid
Path
post sid<AC> Not PII

The SID of the Account that will create the resource.

callback_url
Required
post url PII MTL: 60 DAYS

The URL we should call using callback_method when the trigger fires.

trigger_value
Required
post string Not PII

The usage value at which the trigger should fire. For convenience, you can use an offset value such as +30 to specify a trigger_value that is 30 units more than the current usage value. Be sure to urlencode a + as %2B.

usage_category
Required
post enum:usage_category Not PII

The usage category that the trigger should watch. Use one of the supported usage categories for this value.

callback_method
Optional
post http_method Not PII

The HTTP method we should use to call callback_url. Can be: GET or POST and the default is POST.

friendly_name
Optional
post string Not PII

A descriptive string that you create to describe the resource. It can be up to 64 characters long.

recurring
Optional
post enum:recurring Not PII

The frequency of a recurring UsageTrigger. Can be: daily, monthly, or yearly for recurring triggers or empty for non-recurring triggers. A trigger will only fire once during each period. Recurring times are in GMT.

trigger_by
Optional
post enum:trigger_field Not PII

The field in the UsageRecord resource that should fire the trigger. Can be: count, usage, or price as described in the UsageRecords documentation. The default is usage.

Example 1
Loading Code Sample...
        
        

        Create a new UsageTrigger with parameters

        Fetch a UsageTrigger resource

        get
        https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Triggers/{Sid}.json
        Parameters
        Parameters in REST API format
        account_sid
        Path
        get sid<AC> Not PII

        The SID of the Account that created the UsageTrigger resource to fetch.

        sid
        Path
        get sid<UT> Not PII

        The Twilio-provided string that uniquely identifies the UsageTrigger resource to fetch.

        Example 1
        Loading Code Sample...
              
              

              Fetch a UsageTrigger resource

              Read multiple UsageTrigger resources

              get
              https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Triggers.json
              Parameters
              Parameters in REST API format
              account_sid
              Path
              get sid<AC> Not PII

              The SID of the Account that created the UsageTrigger resources to read.

              recurring
              Optional
              get enum:recurring Not PII

              The frequency of recurring UsageTriggers to read. Can be: daily, monthly, or yearly to read recurring UsageTriggers. An empty value or a value of alltime reads non-recurring UsageTriggers.

              trigger_by
              Optional
              get enum:trigger_field Not PII

              The trigger field of the UsageTriggers to read. Can be: count, usage, or price as described in the UsageRecords documentation.

              usage_category
              Optional
              get enum:usage_category Not PII

              The usage category of the UsageTriggers to read. Must be a supported usage categories.

              Example 1
              Loading Code Sample...
                    
                    

                    Read multiple UsageTrigger resources

                    Update a UsageTrigger Resource

                    post
                    https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Triggers/{Sid}.json

                    Attempts a UsageTrigger's properties update and, if successful, returns the updated resource representation.

                    The returned response is identical to the returned response of a GET request.

                    Parameters
                    Parameters in REST API format
                    account_sid
                    Path
                    post sid<AC> Not PII

                    The SID of the Account that created the UsageTrigger resources to update.

                    sid
                    Path
                    post sid<UT> Not PII

                    The Twilio-provided string that uniquely identifies the UsageTrigger resource to update.

                    callback_method
                    Optional
                    post http_method Not PII

                    The HTTP method we should use to call callback_url. Can be: GET or POST and the default is POST.

                    callback_url
                    Optional
                    post url PII MTL: 60 DAYS

                    The URL we should call using callback_method when the trigger fires.

                    friendly_name
                    Optional
                    post string Not PII

                    A descriptive string that you create to describe the resource. It can be up to 64 characters long.

                    Example 1
                    Loading Code Sample...
                          
                          

                          Update a UsageTrigger Resource

                          Currently, you cannot update the category or value of an existing UsageTrigger. Instead, use POST to create a new UsageTrigger and use DELETE to remove an old UsageTrigger.

                          Delete a UsageTrigger resource

                          delete
                          https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Triggers/{Sid}.json
                          Parameters
                          Parameters in REST API format
                          account_sid
                          Path
                          delete sid<AC> Not PII

                          The SID of the Account that created the UsageTrigger resources to delete.

                          sid
                          Path
                          delete sid<UT> Not PII

                          The Twilio-provided string that uniquely identifies the UsageTrigger resource to delete.

                          Example 1
                          Loading Code Sample...
                                
                                

                                Delete Trigger

                                UsageTrigger Callbacks

                                As soon as the usage value of a UsageTrigger exceeds the TriggerValue, the trigger will fire and Twilio will make an asynchronous HTTP request to the UsageTrigger's CallbackUrl. This request will typically take place within a minute of exceeding the usage threshold.

                                CallbackUrl request parameters

                                Twilio will pass the following parameters to the UsageTrigger's CallbackUrl:

                                Parameter Description
                                AccountSid Your Twilio account id. It is 34 characters long and always starts with the letters AC
                                UsageTriggerSid Unique identifier of the fired UsageTrigger.
                                DateFired Date when the UsageTrigger fired, in GMT.
                                Recurring How the fired UsageTrigger recurs. For non-recurring UsageTriggers: leave empty. For recurring UsageTriggers: choose daily, monthly, or yearly.
                                UsageCategory Usage category watched by the UsageTrigger: choose from supported usage categories.
                                TriggerBy UsageRecord field that fires the UsageTrigger: choose from count, usage, or price.
                                TriggerValue Value at which the UsageTrigger fired.
                                CurrentValue The current value of the usage watched by the UsageTrigger.
                                UsageRecordUri URI of the UsageRecord that this UsageTrigger watched when it fired.
                                IdempotencyToken A random token generated by Twilio and guaranteed to be unique for this particular firing of this UsageTrigger.

                                Best practices with UsageTrigger callbacks

                                When implementing a handler for UsageTrigger's CallbackUrl, your handler may receive HTTP requests more than once. Services that handle duplicate requests and return the same response are called Idempotence.

                                We give you an IdempotencyToken that is unique for each Usage Trigger callback.

                                For more information about Idempotence, see this wiki page.

                                Example: daily recurring UsageTrigger's idempotency token

                                ACed70abd024d3f57a4027b5dc2ca88d5b-FIRES-UTc142bed7b38c4f8186ef41a309814fd2-2012-10-04
                                

                                You can keep track of your IdempotencyToken to properly handle requests to your service and prevent a request from performing the same operation twice.

                                For example, your callback service may send billing notifications via email. For the best possible customer experience, you would want your customers only to receive the billing notification email once.

                                You can follow the test-and-set (external link) pattern to implement idempotent services. In short, you would test for the existence of the IdempotencyToken before processing your application's logic. This allows your application to handle existing tokens and choose the next appropriate step.

                                In the email example, you would have had already sent the email to your customer then you would skip sending the email, instead replying with an HTTP status code of 200.

                                For more information on test-and-set, see this wiki page.

                                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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                                Loading Code Sample...
                                      
                                      
                                      

                                      Thank you for your feedback!

                                      Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                      Sending your feedback...
                                      🎉 Thank you for your feedback!
                                      Something went wrong. Please try again.

                                      Thanks for your feedback!

                                      thanks-feedback-gif