Promo Code APIs

The Promo Code APIs use Promotion, Codes, Generation and Claims objects to provide programmatic access to a promo code engine in the SessionM Platform, one that can generate promo codes so they can be redeemed by a customer for an incentive. Typically, redeeming a promo code awards the customer with points. Promo codes can enable customer service teams and in-store sales teams to reward customers on the spot for activities such as positive feedback and social media sharing. Customer service teams can use promo codes to mitigate negative customer experiences as well.

Promo codes can be one of two possible types: single- or multi-use. The single-use code can be used only once by a customer. Each code is unique and is generated in large promo code lists via the promo code generation function. After the customer redeems the code, it is deactivated.

The multi-use code can be used by multiple customers. The code is reusable across multiple customers. It does not utilize the promo code generation function.

Promo codes are designed to be redeemed by thousands of customers. Therefore, thousands of promo codes might be disseminated across the customer community being serviced by the platform. The organization, however, can protect itself from the risks associated with an unwieldy number of redemptions by setting caps.

API Contingencies and Combinations:
Since promo codes are obtained and claimed by customers, you must create the customers for those transactions. Use the Standard Profile API to create customers and specify the attributes for their standard profiles.
You can set up policies that establish limits on a customer's interactions with promo codes. Lockout objects, which can be retrieved by the Lockout API, constrain the number of attempts a customer can make to redeem a promo code before they get locked out of the system. Limiter objects, retrieved by the Limiter API, constrain the number of promo codes a customer can redeem in a specified period of time. These policies can be configured via the SessionM Administration Portal. Once in place, these policies apply to all promo codes lists, and by extension, all promo codes on those lists. Consult with your SessionM integration engineer for the best way to use these objects to ensure your promo code implementations are secure.
SessionM maintains an historical record of a customer's promo code claims. While the preservation of this record can persist indefinitely, the cost of doing so might be prohibitive. Discuss the retention strategy your organization needs with a SessionM integration expert.

The Promo Code API is a collection of APIs that can be organized into a two distinct groupings: APIs that operate on the promo code list; and, APIs that operate on the promo codes associated with an instance of a promo code list.

This section contains the following discussions:

Promo Code Syntax

Single-use codes are 16 characters long and constituted by the base-31 alphabet:

02345679ABCDEFGHJKLMNPQRSTVWXYZ

Note that the exclusions (1, 8, I, O, U) remove ambiguity for customers trying to read printed codes. For example, the digit "1" might look like the letter "L".

Codes are generated and distributed with uppercase letters. Although, upon entry either uppercase or lowercase are accepted because the values are normalized down to the common storage format prior to lookup.

The makeup of the single-use code is as follows:

  • 1 character for the namespace to allow for versioning as well as different flavors of codes.
  • 4 characters that reflect the promotion.id, padded on the left with a zero to ensure a width fixed at four characters.
  • 11 random characters chosen from the aforementioned alphabet, with the following limitations: Two Vs will never occur next to each other, as this could be confused with a "W" when printed.

Multi-use codes can be of any length <= 64 characters, and made up of any alphanumeric characters. Multi-use codes cannot be 16 characters in length AND consist solely of the single-use promotion code alphabet; this would conflict with the structure of single-use codes.

Promo Codes List API

The Promo Code List API uses Promotion objects to represent promo code lists programmatically. You can invoke these APIs to create or update a list, as well as retrieve an array of promo code lists or the data associated with one in particular.

This API provides the following methods:

Retrieve All Promo Code Lists

Retrieves all promo code lists that utilize promo codes. On success, an object with an array of promo code lists is returned. If this list is empty, there are no lists.

Endpoints

This method offers the following endpoints:

Copy
REST Endpoints
GET  /priv/v1/apps/:api_key/promotions
            

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.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a promotions array, which is shown below:

Copy
JSON Response
{
    "status": "ok",
    "promotions": [
        {
            "id": 77,
            "name": "My Multi Use Promotion",
            "promo_type": "multi_use",
            "global_entry_cap": 20,
            "points": 10,
            "claim_count": 0,
            "starts_at": "2016-06-06T15:01:20Z",
            "ends_at": "9999-12-31T23:59:59Z",
            "codes_generated": 2,
            "multi_use_codes": [
                "WINBIG1",
                "WINBIG2"
            ]
        },
         {
            "id": 79,
            "name": "My Single Use Promotion",
            "promo_type": "single_use",
            "global_entry_cap": 20,
            "points": 10,
            "claim_count": 0,
            "starts_at": "2016-06-06T15:11:50Z",
            "ends_at": "9999-12-31T23:59:59Z",
            "codes_generated": 2
        }
    ]
}

The following table provides details on the promotions array:

Response Attributes for Promotions

Attribute Type Description
id integer Primary key for promo code list.
name string Human-readable, unique name for promo code list.
promo_type enumeration Type of promo code list: single_use or multi-use.
global_entry_cap integer Maximum number of codes that can be redeemed for this promo code list. Value of NULL indicates there is no cap.
points integer Number of points to award when the incentive is points.
claim_count integer Number of successful codes redeemed for the promo code list.
starts_at datetime ISO8601 datetime that promo codes for the promo code list start being accepted.
ends_at datetime ISO8601 datetime that promo codes for the promo code list stop being accepted.
codes_generated integer Number of promo codes generated in the promo code list.
multi_use_codes string array Contains multi-use codes associated with this list. Only available if promo list is of type multi_use
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. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve Specifics on a Promo Code List

Retrieves Promo Code List specifics using the relevant list ID.

Endpoints

This method offers the following endpoints:

Copy
REST Endpoints
GET  /priv/v1/apps/:api_key/promotions/:promotion_id
            

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.
promotion_id Primary key identifying the promotion.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a promotion object, which is shown below:

Copy
JSON Response
{
  "status": "ok",
  "promotion": {
    "id": 1,
    "name": "My Single Use Promotion",
    "promo_type": "single_use",
    "global_entry_cap": 20,
    "points": 10,
    "claim_count": 0,
    "starts_at": "2016-06-06T14:15:36Z",
    "ends_at": "9999-12-31T23:59:59Z",
    "codes_generated": 0,
    "codes_redeemed": 0,
    "generation_requests": []
  }
}

This object is documented in the following table:

Response Attributes for Promotion

Attribute Type Description
codes_generated integer Number of promo codes generated in the promo code list.
codes_redeemed integer Number of promo codes redeemed in the promo code list.
unique_users_redeeming integer Number of unique customers who have claimed codes.
generation_requests array Promo Code Batch generation requests.
id integer ID of of batch requests to generate new promo codes.
state enumeration Current state of the request. Options include: requested, generating, generated and failed.
email_recipients string Comma-separated list of email addresses to email upon generation of codes.
num_codes integer Number of promo codes requested.
name string Human-readable name for generation request.
created_at datetime ISO8601 datetime that promo code generation request was created.
updated_at datetime ISO8601 datetime that promo code generation request was updated.
promo_type enumeration Type of promo code list: single_use or multi-use. For information on syntax requirements, see the Promo Code Syntax.
points integer Number of points to award when the incentive is points.
global_entry_cap integer Maximum number of codes that can be redeemed for this promo code list. Value of NULL indicates there is no cap.
starts_at ISO8601 datetime When promo codes become active. If no value is specified, the list starts immediately. Note that the value for this field must not be in the past and must be less than the value specified for ends_at.
ends_at ISO8601 datetime When promo codes are no longer valid. If no value is specified, codes are valid indefinitely.
claim_count integer Number of successful codes redeemed for the promo code list.
multi_use_codes type Array of strings containing multi-use code(s) associated with this promo code List when it's a multi use code promotion.
organization_id type Foreign key identifier for the organization to which the policy applies.
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
BAD_DATA Unknown promotion.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Create a New Promo Code List

Builds a new promo code list. On success, the ID of the newly created promo code list is returned. If this is empty, no promo code lists exist.

Endpoints

This method offers the following endpoints:

Copy
REST Endpoints
POST /priv/v1/apps/:api_key/promotions
            

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.
Request Object

In addition to a status key-value pair, the response object returned by the method contains a promotion object, which is shown below:

Copy
JSON Request (Single Promo Code List)
{
  "promotion":
  {
    "name": "My Single Use Promotion",
    "promo_type": "single_use",
    "points": 10,
    "starts_at": "2016-06-16T17:41:08Z",
    "ends_at": "2016-07-16T17:41:08Z",
    "global_entry_cap": 4
  }
}
Copy
JSON Request (Multi Promo Code List)
{
  "promotion":
  {
    "name": "My Multi Use Promotion",
    "promo_type": "multi_use",
    "points": 10,
    "starts_at": "2016-06-16T17:41:08Z",
    "ends_at": "2016-07-16T17:41:08Z",
    "global_entry_cap": 4,
    "multi_use_codes": [ "WINBIG" ]
  }
}

This object is documented in the following table:

Request Attributes for Promotion

Attribute Type
Required/Optional
Description
name string
required
Readable, unique name for promo code list.
promo_type enumeration
required
Type of promo code list: single_use or multi-use. For information on syntax requirements, see the Promo Code Syntax
points integer
required
Number of points to award when the incentive is points.
starts_at ISO8601 datetime
optional
When promo codes become active. If no value is specified, the list starts immediately. Note that the value for this field must not be in the past and must be less than the value specified for ends_at.
ends_at ISO8601 datetime
optional
When promo codes are no longer valid. If no value is specified, codes are valid indefinitely.
global_entry_cap integer Maximum number of codes that can be redeemed for this promo code list. Value of NULL indicates there is no cap.
multi_use_codes array
required
Only required for multi use promotions. Array of strings containing multi-use code(s) associated with this promo code list.
Response Object

In addition to a status key-value pair, the response object returned by the method contains the ID of the new list, as shown below:

Copy
JSON Response
{
  "status": "ok",
  "id": 126
}
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
promo_type Can't be blank.
promo_type Is not included in the list.
name Can't be blank.
name Has already been taken.
points Is not a number.
points Must be an integer.
points Must be greater than 0.
promotion_multi_use_codes Multi use code(s) must be provided for multi use promotions.
bad_data Invalid date: \"Not-an-ISO-date\".

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Update a Promo Code List

Modifies an existing promo code list.

Endpoints

This method offers the following endpoints:

Copy
REST Endpoints
PUT /priv/v1/apps/:api_key/promotions/:promotion_id

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.
promotion_id Primary key identifying the promotion.
Request Object

When this method runs, it passes in a request object that contains a promotion object, as shown below:

Copy
JSON Request
{
 "promotion":
  {
    "name": "Updated promo code list",
    "global_entry_cap": 3,
    "ends_at": "2016-06-16T17:41:08Z"
  }
}
Response Object

In addition to a status key-value pair, the response object returned by the method contains a promotion object, as shown below:

Copy
JSON Response
{
  "status": "ok",
  "promotion": {
    "id": 118,
    "name": "Updated promo code list",
    "promo_type": "single_use",
    "points": 10,
    "global_entry_cap": 3,
    "starts_at": "2016-06-16T17:41:08Z",
    "ends_at": "2016-06-16T17:41:08Z",
    "claim_count": 125,
    "codes_generated": 10000
  }
}
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
bad_data No parameters given.
bad_data Unknown promotion.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Promo Codes API

The Promo Codes API exposes the platform's functions for managing promo codes programmatically. This API allows you to manage promo codes and their use, or redemption, by customers. You can invoke one to create a batch of single-use promo codes as well as retrieve the codes associated with a particular promo code list. Once issued, you can discover the status of the batch request. In addition, you can use the API to manage an individual promo code, searching for it and claiming it for an incentive.

This API support the following methods:

Create Batch of Single-use Promo Codes for Promo Code List

Generates a batch of promo codes for a single-use promo code list. On success, an ID for the generation request is returned.

By default, requests are capped at 1 million codes. Contact your SessionM representative if you need to raise the cap.

Batch code generation is handled asynchronously. The workflow is as follows:

  1. Send request to generate codes.
  2. Receive HTTP 200.
  3. Recipient polls status endpoint until codes are ready.
  4. Recipient queries get route to retrieve codes.
Endpoints

This method offers the following endpoints:

Copy
REST Endpoints
POST /priv/v1/apps/:api_key/promotions/:promotion_id/codes

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.
promotion_id Primary key identifying the promotion.
Request Object

When this method runs, it passes in a request object that contains a generation object, which is shown below:

Copy
JSON Request
{
  "generation":
  {
    "num_codes": 1,
    "email_recipients": ["email@domain.com"],
    "name": "batch1"
  }
}

This object is detailed in the following table:

Request Attributes for Generation

Attribute Type
Required/Optional
Description
num_codes integer
required
Number of promo codes requested.
email_recipients array
optional
Array of recipients that are to be notified via email when the batch of promo codes has been successfully generated.
name string
optional
Batch name. Optional field. Length of field limited to 255 characters.

Note that the HTTP_MESSAGE_ID header can be set on the request, and can be used to identify your request later.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a code_generation_request object, which is shown below:

Copy
JSON Response
{
  "code_generation_request":
  {
    "id": 1,
    "state": "generated",
    "email_recipients": null,
    "num_codes": 100,
    "created_at": "2016-06-16T17:41:08Z",
    "updated_at": "2016-06-17T17:41:08Z"
  }
}

This object is detailed in the following table:

Response Attributes for Code Generation

Attribute Type Description
id integer ID of of batch requests to generate new promo codes.
state string Current state of the request. Options include: requested, generating, generated and failed.
email_recipients array
required
Array of recipients that are to be notified via email when the batch of promo codes has been successfully generated.
num_codes integer
required
Number of promo codes requested.
created_at ISO8601 datetime When promo code generation request was created.
updated_at ISO8601 datetime When promo code generation request 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
bad_data Can only perform operation on single use promotions.
bad_data Validation failed: Name must be unique.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve All Promo Codes for Promo Code List

Retrieves a list of all promo codes associated with a promo code list. On success, an array of promo codes is returned along with a status. This method includes endpoint parameters that limit the codes returned by specific generation ID or a message ID.

Endpoints

This method offers the following endpoints:

Copy
REST Endpoints
GET /priv/v1/apps/:api_key/promotions/:promotion_id/codes?<filters>            

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.
promotion_id Primary key identifying the promotion.
code_generation_request_id Identifier for a generation request for this promo list. It is returned via the generate call. Optional field.
message_id HTTP header set when request is generated. Optional field. Omitting the filter will return all codes from a list.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a codes array, which contains multiple promo codes, as shown below:

Copy
JSON Response
{
  "status": "ok",
  "codes": [
    "CODE_1",
    "CODE_2"
  ]
}
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
unknown_promotion Returned when the caller passes in a promotion_id that is not found in the system.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve Status for Promo Code Generation Request

Retrieves a status for the request to generate a batch of promo codes for a promo code list. On success, a status for the promo code generation request is returned.

Endpoints

This method offers the following endpoints:

Copy
REST Endpoints
GET /priv/v1/apps/:api_key/promotions/:promotion_id/codes/status/:code_generation_request_id

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.
promotion_id Primary key identifying the promotion.
promotion_code_generation_request_id Foreign key to the code generation request.
Request Object

Not applicable.

Response Object

This object contains status and state key-value pairs, as shown below:

Copy
JSON Response
{
  "status": "ok",
  "state": "generated"
}

For a description of the response state attribute, see the generation request attributes table for the promotion object.

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
bad_data Unknown code generation request.
bad_data Unknown promotion.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Claim Promo Code

Allows customers to claim a particular promo code using either the ID generated in the platform or the ID generated by an external system.

The code field in the request data is revised accordingly for single- and multi-use codes:

  • All alpha characters are converted to uppercase.
  • Any non alpha-numerics are stripped out.

The following conversions are made for only single-use codes:

  • O (oh) is converted to 0 (zero).
  • 8 is converted to B.
  • 1 is converted to L.
  • U is converted to V.
Endpoints

This method offers the following endpoints:

Copy
REST Endpoints
POST /priv/v1/apps/:api_key/users/:user_id/promotions/claims
POST /priv/v1/apps/:api_key/external/users/:external_id/promotions/claims            

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.
Request Object

When this method runs, it passes in a request object that contains a claim object, which is shown below:

Copy
JSON Request
{
  "claim":
  {
    "code": "P0009BD4TVQXWEH7",
    "audit_data": ""
  }
}

This object is detailed in the following table:

Request Attributes for Claim

Attribute Type
Required/Optional
Description
code string
required
Code being claimed
audit_data string
optional
String of JSON-encoded audit data sent in when the claim was made.
Response Object - Success

The method to claim a promo code can generate a variety of responses indicating success. The sections that follow are dedicated to specific kinds of responses.

In addition to the status value-pair, the method to claim a promo code returns two "child" objects in a successful response:

  • claim
  • promotion

Those objects are shown below:

Copy
JSON Response
{
  "status": "ok",
    "claim": {
      "id": 53,
      "user_id": "46425db4-1d42-11e6-9130-09ab32d14633",
      "promotion_id": 7,
      "code_plaintext": "P0009BD4TVQXWEH7",
      "claim_context": {
        "awards": [
          {
            "type": "points",
            "value": 5
          }
        ]
      },
      "audit_data": {}
    },
    "promotion": {
      "id": 7,
      "name": "Test promotion new 5",
      "promo_type": "single_use",
      "global_entry_cap": 9,
      "points": 5,
      "claim_count": 3,
      "starts_at": "2016-05-17T11:33:59Z",
      "ends_at": "2016-06-16T04:00:00Z",
      "codes_generated" : 5
    }
}
Claim Object

The following table documents the claim object.

Response Attributes for Claim

Attribute Type Description
id integer Primary key for the claim.
user_id integer Primary key for the customer claiming the promo code.
promotion_id integer Identifier of the associated promo code list.
code_plaintext string Formatted code for the customer's input.
claim_context object See table below.
audit_data object JSON-encoded audit data sent in when the claim was made. Next, the data represents the promo code list with promotion.
Claim Context Object

This object contains an awards object, which detailed in the following table:

Response Attributes for Awards in Claim Context

Attribute Type Description
type string The award type.
value integer The value to award.
Promotion Object

This method returns a Promo Code List response object. In addition to a status key-value pair, this object contains the promotion object.

Response Object - Failure

The method to claim a promo code can generate a variety of responses indicating failure. The sections that follow are dedicated to specific kinds of error responses when a promo code is claimed.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Claim Error Response Due to Promo Code Not Found

In addition to the status key-value pair, the response object returned when a promo code is not found contains a few other attributes. The number_of_attempts_before_lockout key-value pair is the number of attempts a customer can make before being locked out of the promotion.

The response also includes three "child" objects:

  • errors
  • lockout_record
  • lockout_policy

These objects are shown below:

Copy
JSON Response (Promo Code Not Found)
{
 "status": "error",
 "errors": {
   "code": "code_not_found",
   "message": "claim code can not be found"
 },
 "lockout_record": {
   "id": 8,
   "event_type": "promo_code",
   "user_id": "46425db4-1d42-11e6-9130-09ab32d14633",
   "consecutive_count": 3,
   "cumulative_count": 18,
   "reset_counter": 0
 },
 "lockout_policy": {
   "id": 2,
   "starts_at": "2016-04-11T16:02:03Z",
   "ends_at": "2016-07-11T16:02:03Z",
   "organization_id": 7,
   "type": "promo_code_lockout",
   "consecutive_count": 10,
   "cumulative_count": 30,
   "lockout_duration": 86400
 },
"number_of_attempts_before_lockout": 7
}

The following sections contain tables that provide details on these objects.

Errors Object

Attribute Type Description
code string Error code for the error. Includes:

- code_not_found, which displays if the promo code isn't found.
- user_locked_out, which displays if the customer is locked out.
- user_perm_locked_out, which displays if the customer is permanently locked out.
- cancelled_code, which displays if the code was cancelled by the operator.
- inactive_promotion, which displays if the promotion is inactive.
- claimed_code, which displays if the code is already claimed.
- no_available_cap, which displays if no global entry cap is available.
message string Human readable string useful for API debugging. Refrain from creating any business logic that depends on it; instead, use one of the error codes shown in the row above.

Lockout Record Object

Attribute Type Description
id integer Lockout record ID associated with a customer's lockout.
event_type string Enumeration that defines type of lockout being tracked, promo_code.
user_id string Identifier for customer making the claim or being locked out.
consecutive_count integer Number of lockout-eligible events that have happened in a row for a specific type.
cumulative_count integer Number of lockout-eligible events that occurred all time.
lockout_expires datetime Time at which lockout expires. If customer has hit their all-time lockout, then this value reflects datetime.max.
reset_counter integer Tracks number of times counters have been reset by an administrator.

Lockout Policy Object

Attribute Type Description
id integer Identifier for the customer's lockout policy.
starts_at datetime ISO8601 datetime that lockout policy is effective.
ends_at datetime ISO8601 datetime that lockout policy stops being effective.
organization_id integer Foreign key identifier for the organization to which the policy applies.
type string Type of policy, promo_code_lockout.
consecutive_count integer Number of lockout-eligible events that a customer can do in a row for a specific type before being locked out temporarily.
cumulative_count integer Number of lockout-eligible events that a customer can do before being locked out permanently.
lockout_duration integer Lockout duration in seconds.
Claim Error Response Due to Customer Lockout

Claim error responses due to customer lockouts contain attributes that are similar to those shown for error responses due to the promo code not being found. For more information, see Claim Error Response Due to Promo Code Not Found.

Claim Error Response Due to Customer Lockout Hitting Cumulative Count

Claim error responses due to customer lockout hitting a cumulative count contain attributes that are similar to those shown for error responses due to the promo code not being found. For more information, see Claim Error Response Due to Promo Code Not Found.

Consider the following sample:

Copy
JSON Response (Promo Code Not Found Due to Customer Lockout from Hitting Cumulative Count)
{
  "status": "error",
  "errors": {
    "claim": {
      "promotion_id": "promo list id",
      "user_id": "user id"
      },
      "code": "user_perm_locked_out",
      "message": "user is permanently locked out"
    },
 "lockout_record": {
   "id": 8,
   "event_type": "promo_code",
   "user_id": "46425db4-1d42-11e6-9130-09ab32d14633",
   "consecutive_count": 3,
   "cumulative_count": 30,
   "lockout_expires": "9999-01-01T00:00:00Z",
   "reset_counter": 0
 },
 "lockout_policy": {
   "id": 2,
   "starts_at": "2016-04-11T16:02:03Z",
   "ends_at": "2016-07-11T16:02:03Z",
   "organization_id": 7,
   "type" : "promo_code_lockout",
   "consecutive_count": 10,
   "cumulative_count": 30,
   "lockout_duration": 86400
 },
"number_of_attempts_before_lockout": 0
}
Claim Error Response for a Cancelled Code

Claim error responses for a cancelled code contain attributes that are similar to those shown for error responses due to the promo code not being found. For more information, see Claim Error Response Due to Promo Code Not Found.

Consider the following sample:

Copy
JSON Response (Cancelled Code)
{
   "status": "error",
   "errors":
   {
      "code": "cancelled_code",
      "message": "Code cancelled by operator"
    }
}
Claim Error Response for an Inactive Promotion

Claim error responses for an inactive promotion contain attributes that are similar to those shown for error responses due to the promo code not being found. For more information, see Claim Error Response Due to Promo Code Not Found.

Consider the following sample:

Copy
JSON Response (Claim Error for Inactive Promotion)
{
  "status": "error",
  "errors": {
   "code": "inactive_promotion",
   "message": "inactive promotion"
   }
 }
Claim Error Response for Already Claimed Code

Claim error responses for already claimed codes contain attributes that are similar to those shown for error responses due to the promo code not being found. For more information, see Claim Error Response Due to Promo Code Not Found.

Consider the following sample:

Copy
JSON Response (Claim Error for Already Claimed Code)
{
  "status": "error",
  "errors": {
  "code": "claimed_code",
  "message": "code is already claimed"
  }
}
Claim Error Response for No Available Global Entry Cap

Claim error responses for no available global entry cap contain attributes that are similar to those shown for error responses due to the promo code not being found. For more information, see Claim Error Response Due to Promo Code Not Found.

Consider the following sample:

Copy
JSON Response (Claim Error for No Available Global Entry Cap)
{
  "status": "error",
  "errors": {
  "code": "no_available_cap",
  "message": "no available cap"
  }
}

Retrieve Invalid Promo Codes Claimed by Customer

This method retrieves promo codes that were deemed invalid when claimed by a customer. When successful, the invalid codes are returned along with their timestamp and reason for being invalid.

Endpoints

This method offers the following endpoints:

Copy
REST Endpoints
GET /priv/v1/apps/:api_key/users/:user_id/promotions/claims/errors
GET /priv/v1/apps/:api_key/external/users/:external_id/promotions/claims/errors            

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.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a codes array, which is shown below:

Copy
JSON Response
{
 "codes":
 [
    { "code": "68723695",
      "created_at": "2016-04-21T16:02:03Z",
      "error_reason": "invalid"
    }
 ]
}

This array is detailed in the following table:

Response Attributes for Codes

Attribute Type Description
code string Invalid promo code claimed by customer.
created_at datetime ISO8601 datetime that the error occurred.
error_reason string Obtained from the enumeration for the promotion_code_claim_error class. Enumeration values for the error reason include. These values include invalid, not_active, cancelled, and claimed.
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. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Seаrch Promo Codes by Criteria

Filters for and retrieves claimed promo codes based on customer ID or external ID.

Endpoints

This method offers the following endpoints:

Copy
REST Endpoints
GET /priv/v1/apps/:api_key/promotions/claims/?filter criteria
            

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 making the claim.
external_id Identifier for a customer (claimant) in an external system integrating with the SessionM Platform.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a codes array, which is shown below:

Copy
JSON Response (Promo Code Found)
{
  "codes":
  [
    {
      "code": 923481653,
      "type": "single_use",
      "claim": {
         "claimdatetime": "2016-10-07T15:48:28Z",
         "user_id": "4642b4-142-1e6-9130-09ad14633",
         "external_id": "7642b4-09ad149935",
         "audit_data": "\"\"",
         "claim_details": "prize details",
         "promotion_id": "1",
         "promotion_name": "grand prize"
       }
    }
  ]
}

This array is detailed in the following tables:

Response Attributes for Codes

Attribute Type Description
code string Promo code searched for by the customer.
type string Enumeration for single-use or multi-use promo code.
claim object Empty if none exist. For more information, see table below.

Response Attributes for Claim

Attribute Type Description
claimdatetime datetime ISO8601 formatted timestamp for the claimed code.
user_id string ID of the claimant.
external_id string ID of the claimant if the customer has an identifier on an external system.
audit_data object JSON-encoded audit data sent in at the time of the claim.
claim_details string Description of what was claimed.
promotion_id integer ID of the associated promotion.
promotion_name string Name of the associated promotion.

If no codes are found, then the returned array is empty. If the code is a multi-use code and the search is by code only, no claim data is returned since the thousands of claimers could exist.

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. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Seаrch by Promo Code

Filters for and retrieves data about a specific promo code.

Endpoints

This method offers the following endpoints:

Copy
REST Endpoints
GET /priv/v1/apps/:api_key/promotions/codes?code=<code>
            

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.
code Specified promo code.
Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains several attributes, some of which are other "child" objects, as shown below:

Copy
JSON Response (Unclaimed Valid Promo Code Found in Search)
{
   "cancellation":null,
   "claim":null,
   "multi_use":false,
   "promotion":{
      "claim_count":0,
      "codes_generated":100,
      "codes_redeemed":0,
      "ends_at":"9999-12-31T23:59:59Z",
      "generation_requests":[
         {
            "created_at":"2016-07-27T16:24:49Z",
            "email_recipients":"machism2007@outlook.com",
            "id":1,
            "name":"First Batch of Codes",
            "num_codes":100,
            "state":"generated",
            "updated_at":"2016-07-27T16:27:02Z"
         }
      ],
      "id":199,
      "name":"Latest Single Use Promotion",
      "points":10,
      "promo_type":"single_use",
      "starts_at":"2016-07-26T19:03:41Z",
      "unique_users_redeeming":0
   },
   "status":"ok"
}
Copy
JSON Response (Claimed Valid Promo Code Found in Search)
{
   "cancellation":null,
   "claim":{
      "audit_data":"\"1\"",
      "claim_context":{
         "awards":[
            {
               "type":"points",
               "value":25
            }
         ]
      },
      "code_plaintext":"P007G4RBHXQ073JW",
      "created_at":"2016-07-27T22:44:05Z",
      "id":17,
      "promotion_id":200,
      "user_id":"0f8691fc-43a6-11e6-9510-2cee2933ac55"
   },
   "multi_use":false,
   "promotion":{
      "claim_count":1,
      "codes_generated":50,
      "codes_redeemed":1,
      "ends_at":"9999-12-31T23:59:59Z",
      "generation_requests":[
         {
            "created_at":"2016-07-27T22:38:02Z",
            "email_recipients":null,
            "id":1,
            "name":"50 codes",
            "num_codes":50,
            "state":"generated",
            "updated_at":"2016-07-27T22:38:20Z"
         }
      ],
      "id":200,
      "name":"Promo Code List 1000",
      "points":25,
      "promo_type":"single_use",
      "starts_at":"2016-07-27T22:37:29Z",
      "unique_users_redeeming":1
   },
   "status":"ok"
}

The following table provides details on the response object:

Response Attributes for Promo Code

Attribute Type Description
cancellation object Serialized cancellation model as defined by API to cancel a code; null if it has not yet been cancelled. For more information, see Cancel a Promo Code.
claim object Empty if none exist. Otherwise, if successful, the claim is represented with the data below. For more information on the claim object, see its related discussion in Successful Responses for Claiming a Promo Code.
multi_use boolean If the promo code can be used multiple times.
promotion object All the base information returned by the API that retrieves specifics for a promo code list. For more information on this object, see the table detailing the promotion object.
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
invalid_code Promo code found in search is invalid.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Cancel Promo Code

Marks a promo code as operator cancelled, which means it is no longer available. It provides an effective way of handling lost or stolen codes. Only single-use codes can be cancelled.

Endpoints

This method offers the following endpoints:

Copy
REST Endpoints
DELETE /priv/v1/apps/:api_key/promotions/codes            

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.
Request Object

When this method runs, it passes in a request object that contains a codes array, which is shown below:

Copy
JSON Request
{
    "codes": ["SOME_VALID_CODE", "SOME_INVALID_CODE"]
}            

The array is detailed in the following table:

Request Attributes for Codes

Attribute Type
Required/Optional
Description
codes array
required
Array of codes to cancel.
Response Object

In addition to a status key-value pair, the response object returned by the method contains the attributes shown below:

Copy
JSON Response
{
"codes_cancelled": ["SOME_VALID_CODE"],
"codes_failed":
    [
      {
        "code" : "SOME_INVALID_CODE",
        "reason" : "code could not be found"
      }
    ]
}

The response object is detailed in the following table:

Response Attributes for Cancelling a Promo Code

Attribute Type Description
codes_cancelled array Promo codes marked as cancelled.
codes_failed object Promo codes unable to be cancelled. Object contains the code that failed as well as the reason as to why it failed.
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.
limiter_type_invalid Invalid limiter_type specified.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.