Limiter API
The Limiter API allows you to keep running tallies of a customer’s events over periods of time. For promotion codes, limiters limit the number of codes that a customer can enter within a quantum (weekly, monthly, or yearly time period).
Limiters go hand in hand with a policy that defines how to govern the event in question. The policy defines the configuration that drives the implementation of the limiter. The limiter is the real-time counter of the customer’s actions with respect to the policy definition.
The Limiter API is designed to retrieve existing limiter policies. These policies are configured in the platform using the SessionM Administration Portal. For more information, talk to your SessionM integration engineer.
Limiter policies can be configured to limit how many promo code claims a customer can make within one or more quantums. An organization can define a policy that covers one, two, or all three supported quantums. For example, one organization may wish to put a limit of 10 codes per week and 20 codes per month, while another organization may only want to limit its customers to 1000 codes per year.
This API offers a method to implement the retrieval of limiter policies and customer specific policy data.
Retrieve Limiter Policies and Customer Specific Policy Data
This method retrieves current active limiter policies policy data defined for specific customers based on their user_id or external_id.
Endpoints
This method offers the following endpoints:
GET /priv/v1/apps/:api_key/users/:user_id/limiters?limiter_type=<type>
GET /priv/v1/apps/:api_key/external/users/:external_id/limiters?limiter_type=<type>
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
user_id | Internal identifier for the customer within the SessionM Platform. |
external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
limiter_type | Filter that retrieves a limiter policy in support of lockouts associated with promo codes. Current valid values for limiter_type include promotion_code_claim. For example: limiter_type=promotion_code_claim |
Request Object
Not applicable.
Response Object
In addition to a status key-value pair, the response object returned by the method contains two objects. They include:
- policy
- player_limiters
These objects are shown below:
{
"policy" :
{
"starts_at" : "2016-12-06 16:00:00",
"ends_at" : "2016-12-06 16:00:00",
"created_at" : "2016-12-06 16:00:00",
"updated_at" : "2016-12-07 16:00:00",
"data" :
{
"quantums" :
{
"weekly": 2
}
}
},
"player_limiters" :
[
{
"id" : 4,
"limiter_type" : "promotion_code_claim",
"quantum" : "weekly",
"starts_at": "2016-12-06 16:00:00",
"ends_at" : "2016-12-16 16:00:00",
"counter" : 6,
"created_at" : "2016-12-06 16:00:00",
"updated_at" : "2016-12-07 16:00:00"
}
]
}
Policy Object
For more information see Policy Object.
Player Limiters Object
The following table provides details on the player_limiters object:
Response Attributes for Player Limiters
Attribute | Type | Description |
---|---|---|
id | integer | ID of the customer that is performing events. |
limiter_type | enumeration | Enumeration that provides types for limiter policies, including promotion_code_claim. |
quantum | enumeration | Enumeration that provides values that correspond to periods of time, including: weekly, monthly and yearly. |
starts_at | datetime | ISO8601 formatted datetime at which the limiter policy becomes effective. |
ends_at | datetime | ISO8601 formatted datetime at which the limiter policy is no longer effective. |
counter | integer | Unique index on player_id, org_id, limiter_type and quantum. |
created_at | datetime | ISO8601 formatted datetime at which the limiter policy was created. |
updated_at | datetime | ISO8601 formatted datetime at which the limiter policy was updated. |
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:
Code | Reason |
---|---|
user_not_found | Customer not found for client-specific limiter policy data. |
limiter_type_invalid | Limiter type specified is invalid. |
If there is no active policy, then the policy field's value will be null. Furthermore, if there is no active policy, then the customer node will also be null, regardless of whether there is active customer data. This could happen if, for example, the policy expires mid-quantum. If there is no active customer record, then the customer node's value will be null.
For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.