OCS options

Learn about OCS options and their dedicated APIs

Introduction

An option is a choice given to your subscribers which may modify the behavior of their connectivity services.

It differs from a product in the following ways:

When present in the catalog, the option exists for all your subscribers
It has different states (often on/off) that you can manipulate for each subscriber
It exists from the activation of the subscriber until termination, you don't have to explicitly subscribe or unsubscribe to it

Available options are:

Data safeguard

The data safeguard option can help MVNOs comply with EU anti-billshock regulation which sets a monthly cut-off limit for roaming data. Once the cut-off has been reached, all roaming data traffic is blocked to avoid any bill shock to a subscriber. This limit can be lifted for the current monthly period by the subscriber who is able to explicitly opt out from this protection.

This option is active by default when a subscriber is activated. The spent counter is reset on the 1st of each calendar month. However, it is possible to change the renewal day via API (between the 1st and 28th of the month).

This option has three states:

active: The protection is active
temporarily-inactive: The protection is deactivated but only for the current period, no traffic limitation will be applied. The protection will automatically revert back to active again when the next period starts.
permanently-inactive: The protection is completely deactivated

Data safeguard option lifecycle

Overspend safeguard

The overspend safeguard option is an option which controls usage for out-of-bundle services. Once the cut-off has been reached, out-of-bundle services are blocked.

This option is inactive by default when a subscriber is activated. When activating the option a cut-off limit must be specified. The spent counter is reset on the 1st of the month. However, it is possible to change the renewal day via API (between the 1st and 28th of the month). The current as well as the next period's cut-off limits can also be adjusted via API.

This option has two states:

active: The protection is active
inactive: The protection is inactive

Overspend safeguard option lifecycle

Payment safeguard

The payment safeguard option can help MVNOs to comply with EU PSD2 / UK PSR 2017 which sets a monthly cut-off limit for third-party payments via the subscriber's mobile phone bill (including premium SMS). Once the cut-off limit has been reached, third party payments are blocked to avoid any bill shock to a subscriber.

This option is active by default when a subscriber is activated. The spent counter is reset on the 1st of the month. However, it is possible to change the renewal day via API (between the 1st and 28th of the month).

This option has two states:

active: The protection is active
inactive: The protection is inactive

Payment safeguard option lifecycle

Option Catalog

This API allows you to retrieve option(s) from your catalog.

Retrieve all options by COS

Operation used to retrieve all option(s) from your catalog, so you can discover which ones are configured.

Retrieve data safeguard option

Operation used to consult the data safeguard option details in your catalog. From the response, you can check:

The configuration of the cutOff limit
All possible states for this option

Retrieve overspend safeguard option

Operation used to consult the overspend safeguard option details in your catalog. From the response, you can check:

All possible states for this option

Retrieve payment safeguard option

Operation used to consult the payment safeguard option details in your catalog. From the response, you can check:

The configuration of the cutOff limit
All possible states for this option

Option Inventory

This API allows you to retrieve the inventory of option(s) for your subscribers.

Retrieve subscriber option(s) inventory

Operation used to retrieve the inventory of all options for a given subscriber using their MSISDN.

Retrieve subscriber data safeguard option state

Operation used to retrieve the state of the data safeguard option for a given subscriber with some additional information such as:

state: the current state of this option
limit: the cut-off limit value
currency: the cut-off currency
spent: the value of roaming data usages spent during the current period. Provided only when the data safeguard option is active.
reached: a flag indicating if your subscriber has already reached the cut-off limit and can no longer access roaming data. Once the remaining amount of the cut-off amount limit is under 50 cents this flag will be set to false. Provided only when the data safeguard option is active.
eligibleStates: all reachable states according to the current one

List of possible states:

active: your subscriber is protected by the data safeguard option. They can enjoy roaming data up to the defined cut-off amount limit.
temporarily-inactive: your subscriber has opted-out from the data safeguard option protection for the current period and can use roaming data without limitation
permanently-inactive: your subscriber has definitively opted-out from the data safeguard option protection

Retrieve subscriber overspend safeguard option state

Operation used to retrieve the state of the overspend safeguard option for a given subscriber with some additional information such as:

state: the current state of this option
currentlimit: the cut-off current limit value
nextlimit: the cut-off next period limit value
currency: the cut-off currency
spent: the value of out-of-bundles usages spent during the current period
reached: a flag indicating if your subscriber has already reached the cut-off limit and can no longer access out-of-bundle usages. Once the remaining amount of the cut-off amount limit is under 50 cents this flag will be set to false.
eligibleStates: all reachable states according to the current one

List of possible states:

active: your subscriber is protected by the overspend safeguard option. They can enjoy out-of-bundle usages up to the defined cut-off amount limit.
inactive: your subscriber is not eligible to access out-of-bundle usages

Retrieve subscriber payment safeguard option state

Operation used to retrieve the state of the payment safeguard option for a given subscriber with some additional information such as:

state: the current state of this option
limit: the cut-off limit value
currency: the cut-off currency
spent: the value of third-party payments (including premium SMS) spent during the current period. Provided only when the payment safeguard option is active.
reached: a flag indicating if your subscriber has already reached the cut-off limit and can no longer access third-party payment services (including premium SMS). Once the remaining amount of the cut-off amount limit is under 50 cents this flag will be set to false. Provided only when the payment safeguard option is active.
eligibleStates: all reachable states according to the current one

List of possible states:

active: your subscriber is protected by the payment safeguard option. They can enjoy premium usages up to the defined cut-off amount limit.
inactive: your subscriber is not protected by the payment safeguard option and can use premium usages without limitation

Option Subscriptions

This API allows you to change the state of a given option of your subscriber.

Change subscriber data safeguard option

This operation allows you to change the renewal day or the state of the data safeguard option for a given subscriber.

Change subscriber overspend safeguard option

This operation allows you to change the renewal day, cutoff limits or the state of the overspend safeguard option for a given subscriber.

Change subscriber payment safeguard option

This operation allows you to change the renewal day or the state of the payment safeguard option for a given subscriber.