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.

API Contingencies and Combinations:
Limiters can configure how many promo code claims a customer can make. Therefore, you must create the customers prior to making that configuration. Use the Standard Profile API to create customers and specify the attributes for their standard profiles.
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:

Copy
REST 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:

Copy
JSON Response
{
  "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.