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.
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
- Retrieve specifics on a promo code list
- Create a new promo code list
- Update a promo code list
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:
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:
{
"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:
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:
{
"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:
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:
{
"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
}
}
{
"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:
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:
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:
{
"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:
{
"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
- Retrieve all promo codes for promo code list
- Retrieve status for promo code generation request
- Claim promo code
- Retrieve invalid promo codes claimed by customer
- Seаrch promo codes by criteria
- Seаrch by promo code
- Cancel promo code
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:
- Send request to generate codes.
- Receive HTTP 200.
- Recipient polls status endpoint until codes are ready.
- Recipient queries get route to retrieve codes.
Endpoints
This method offers the following endpoints:
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:
{
"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:
{
"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:
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:
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:
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:
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:
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:
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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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:
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:
{
"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:
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:
{
"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:
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:
{
"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"
}
{
"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:
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:
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:
{
"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.