This guide will walk you through how to manage your Standard Service's usage settings.
It is possible to control a Standard Service's usage of several bands of voice and data traffic.
A period of usage alerting and capping runs from the first of the month until the end of the month. In order to impose new usage settings onto your service, you must create a new "usageControls/settings" resource with a "schedule" that refers to your Service resource using its ID. The "applyDate" of a "schedule" on a new queued usage resource must be the first day of a future month.
In order to provision queued usage settings, you must already have an "ACTIVE" or "SUSPENDED" standard Service; Standard Provision & Activate
It is important to note that Queued Usage Settings will continue to be re-applied to your service at the start of each period of usage, until they are either superseded by a new usage settings resource with a more recent "applyDate", or they are deleted
See the Create usage settings section of the API spec for a complete reference.
POST https://api-test.gamma.co.uk/mobile/v1/usageControls/settings { "voice": { ... }, "data": { ... }, "boltOns": { ... }, "schedule": [ { "serviceId": 1234, "applyDate": "2023-08-01" } ], "channelPartnerId": 12345 }
The response will contain the newly created queued usage settings including their ID. This ID will be needed to reference the queued usage settings in future requests. You can search usage settings if you need to find the IDs of queued usage settings associated with a particular service.
You will also receive a "Location" Response Header that will contain the link to your newly created resource.
If you do not want to create alerts or capping for any particular category of usage (for example, "voice") then it can safely be omitted from your POST request. The "schedule" field is required, as it states which service the controls will apply to, and also the date that they will apply from. When creating queued usage settings, this date must be on the first of a future month.
It is also possible to remove a service's usage settings on a future date by creating a queued usage resource with null settings with a relevant schedule:
POST https://api-test.gamma.co.uk/mobile/v1/usageControls/settings { "voice": null "data": null "boltOns": null, "schedule": [ { "serviceId": 1234, "applyDate": "2023-09-01" } ], "channelPartnerId": 12345 }
It is also possible to delete all queued usage settings that reference the service. By doing this the service will have its usage settings removed at the start of the next period of usage.
If you would like to find Queued Usage Settings for a given Standard Service, you can search the base resource path.
See the Search usage settings section of the API spec for a complete reference.
GET https://api-test.gamma.co.uk/mobile/v1/usageControls/settings?serviceId=1234
This will return a list of queued usage settings that have a schedule which is associated with the serviceId stated in the query parameter:
[ { "voice": { ... }, "data": { ... }, "boltOns": { ... }, "schedule": [ { "serviceId": 1234, "applyDate": "2023-08-01" } ], "channelPartnerId": 12345 }, { "voice": { ... }, "data": { ... }, "boltOns": { ... }, "schedule": [ { "serviceId": 1234, "applyDate": "2023-09-01" } ], "channelPartnerId": 12345 } ]
There will be at most one queued usage settings resource with a schedule containing a historic "applyDate" at a time, as the resources are automatically deleted as they are superseded by resource with more recent schedules coming into effect. This means that it is possible to know which settings will take effect on your service at the start of any given period of usage by finding the queued usage settings resource with the most recent schedule to that period of usage.
You can only update queued usage settings if all of the objects withing the "schedule" array have a future "applyDate". If you need to update a historic queued usage setting resource, you should instead create a new usage settings resource with the desired schedule. When these new usage settings are applied, any defunct historic usage settings resource will be automatically deleted. In this way there will be at most one usage settings resource with a schedule containing an "applyDate" in the past associated with any given Standard Service.
See the Update usage settings section of the API spec for a complete reference.
PATCH https://api-test.gamma.co.uk/mobile/v1/usageControls/settings/334 { "voice": { "ukEu": { "alertMins": 700, "capMins": 1000 } } }
The response will be 202 (Accepted) with no content. This indicates that the change will not have been applied immediately. Resources will be locked while a change is being applied. This is indicated by the presence of the "LOCKED" value in the resource's "readOnlyAttributes" property. You can use the request history resource to track the progress of asynchronous requests.
Should you want to stop queued usage settings taking effect on your service, then it is necessary to delete them.
It is possible to delete your historic queued usage settings. When this is done, assuming there are no future usage settings with a relevant schedule to replace them at the start of the next period of usage, then all usage settings will be removed from the service. A service will only have usage settings applied at the start of a usage period if there is a queued usage settings resource with a "schedule" with an "applyDate" either on or before that period.
See the Delete Usage settings section of the API spec for a complete reference.
DELETE https://api-test.gamma.co.uk/mobile/v1/usageControls/settings/334
The response will be 202 (Accepted) with no content. This indicates that the change will not have been applied immediately. Resources will be locked while a change is being applied. This is indicated by the presence of the "LOCKED" value in the service resource's "readOnlyAttributes" property. You can use the request history resource to track the progress of asynchronous requests.
When new usage settings are applied, any defunct historic usage settings resource will be automatically deleted. In this way there will be at most one usage settings resource with a schedule containing an "applyDate" in the past associated with any given Standard Service.
Once you have created your Queue Usage Settings, and the "applyDate" of your schedule has been reached, the usage settings will take effect.
You can tell what usage settings are currently in effect on your service by inspecting the "usageControls" sub-resource of your Standard Service resource.
See the Get Service usage configuration section of the API spec for a complete reference.
GET https://api-test.gamma.co.uk/mobile/v1/services/standard/456/usageControls
Note that the example ID given here of "456" is the id of the Standard Service resource to which the active usage controls belong, rather than the id of the queued usage settings resource that caused them to come into effect.
{ "self": "https://api-test.gamma.co.uk/mobile/v1/services/standard/456/usageControls", "settings": { "voice": { ... }, "data": { ... }, "boltOns": { ... } }, "notifications": { "alertOwningService": true, "alertMsisdns": [], "alertEmails": [] } }
The format of these settings is very similar to the queued settings that spawned them, apart from a few key details.
The first of these important differences is the presence of the "notifications" field. The settings here define what will receive notifications caused by alerts and caps being reached. You can update these notification settings
Another key difference lies inside the settings for the bands themselves. For example, within the "voice" field:
{ ... "settings": { ... "voice": { "ukEu": { "alertMins": 700, "capMins": 1000 "capped": true }, "row": null }, ... } ... }
Each control will contain a "capped" field. This is used to display the current status of capping for that control. In the above example it can be seen that for "settings/voice/ukEu/capped" the value is true. This means the service has reached its cap for UK/EU voice traffic, and will no longer be able to make calls in those regions.
It is possible to update your current usage settings to remove settings that are in effect for the current period of usage.
In order to control what will receive notifications when alerts and caps are reached, you must amend the "notifications" field of the "usageControls" sub-resource of the relevant Standard Service resource. You can find your current settings by viewing your services current usage settings
See the Update a Service's usage configuration section of the API spec for a complete reference.
PATCH https://api-test.gamma.co.uk/mobile/v1/services/standard/456/usageControls { "notifications": { "alertOwningService": true, "alertMsisdns": ["447123456789"], "alertEmails": ["test@test.com"] } }
Note that the example ID given here of "456" is the id of the Standard Service resource to which the usage controls belong, rather than the id of the queued usage settings resource that caused them to come into effect.
The "alertOwningService" field controls whether the MSISDN associated with the service resource itself should receive SMS alerts. The "alertMsisdns" and "alertEmails" lists are used to specify other MSISDNs and email addresses that should receive alerts.
You may wish to alter the usage settings that are currently in effect for a Standard Service. It is currently only possible to remove settings, in order to lift in-place caps or remove all alerting and capping potential. You can find your current settings by viewing your services current usage settings
PATCH https://api-test.gamma.co.uk/mobile/v1/services/standard/456/usageControls { "settings": null }
In the above example, all of the settings for the usage controls associated with the service with id 456 have been set to null.
Should this change be applied successfully, this will mean there will be no usage settings in effect for the service for the remainder of the current period of usage. Any usage related caps that are in place will also be lifted as a result of this change
PATCH https://api-test.gamma.co.uk/mobile/v1/services/standard/456/usageControls { "settings": { "voice": null } }
In the above example, only the "voice" field has been set to null. Should this change be applied successfully, this will mean there will be no voice usage settings in effect for the service for the remainder of the current period of usage. All other bands of traffic will continue to be alerted or capped as before your change. Any voice based usage related caps that are in place will also be lifted as a result of this change
PATCH https://api-test.gamma.co.uk/mobile/v1/services/standard/456/usageControls { "settings": { "voice": { "ukEu": null } } }
In the above example, only the "voice" fields "ukEu" field has been set to null. Should this change be applied successfully, this will mean there will be no voice usage settings for the UK/EU region in effect for the service for the remainder of the current period of usage. All other bands of traffic will continue to be alerted or capped as before your change. If UK/EU voice traffic had a usage related cap in place, it will be lifted as a result of this change
Keep in mind these changes may or may not be permanent. The settings that will take effect in future periods of usage are defined by queued usage settings that reference your service