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.

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
• Promo Codes List API
• Promo Codes API

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 for Retrieve All Promo Code Lists

This method offers the following endpoints:

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 for Retrieve All Promo Code Lists

The following parameters are available when specifying the endpoint for this method:

Request Object for Retrieve All Promo Code Lists

Not applicable.

Response Object for Retrieve All Promo Code Lists

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

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

Statuses and Errors for Retrieve All Promo Code Lists

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 for Retrieve Specifics on a Promo Code List

This method offers the following endpoints:

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 for Retrieve Specifics on a Promo Code List

The following parameters are available when specifying the endpoint for this method:

Request Object for Retrieve Specifics on a Promo Code List

Not applicable.

Response Object for Retrieve Specifics on a Promo Code List

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

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

Statuses and Errors for Retrieve Specifics on a Promo Code List

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:

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 for Create a New Promo Code List

This method offers the following endpoints:

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 for Create a New Promo Code List

The following parameters are available when specifying the endpoint for this method:

Request Object for Create a New Promo Code List

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

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
  }
}

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

Response Object for Create a New Promo Code List

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:

JSON Response

{
  "status": "ok",
  "id": 126
}

Statuses and Errors for Create a New Promo Code List

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:

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 for Update a Promo Code List

This method offers the following endpoints:

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 for Update a Promo Code List

The following parameters are available when specifying the endpoint for this method:

Request Object for Update a Promo Code List

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

JSON Request

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

Response Object for Update a Promo Code List

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

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 for Update a Promo Code List

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:

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
• Search promo codes by criteria
• Search 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:

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 for Create Batch of Single-use Promo Codes for Promo Code List

This method offers the following endpoints:

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 for Create Batch of Single-use Promo Codes for Promo Code List

The following parameters are available when specifying the endpoint for this method:

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

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

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

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

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

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:

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

Statuses and Errors for Create Batch of Single-use Promo Codes for Promo Code List

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:

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 for Retrieve All Promo Codes for Promo Code List

This method offers the following endpoints:

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 for Retrieve All Promo Codes for Promo Code List

The following parameters are available when specifying the endpoint for this method:

Request Object for Retrieve All Promo Codes for Promo Code List

Not applicable.

Response Object for Retrieve All Promo Codes for Promo Code List

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:

JSON Response

{
  "status": "ok",
  "codes": [
    "CODE_1",
    "CODE_2"
  ]
}

Statuses and Errors for Retrieve All Promo Codes for Promo Code List

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:

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 for Retrieve Status for Promo Code Generation Request

This method offers the following endpoints:

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 for Retrieve Status for Promo Code Generation Request

The following parameters are available when specifying the endpoint for this method:

Request Object for Retrieve Status for Promo Code Generation Request

Not applicable.

Response Object for Retrieve Status for Promo Code Generation Request

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

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 for Retrieve Status for Promo Code Generation Request

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:

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 for Claim Promo Code

This method offers the following endpoints:

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 for Claim Promo Code

The following parameters are available when specifying the endpoint for this method:

Request Object for Claim Promo Code

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

JSON Request

{
  "claim":
  {
    "code": "P0009BD4TVQXWEH7",
    "audit_data": ""
  }
}

This object is detailed in the following table:

Request Attributes for Claim

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:

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

Claim Context Object

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

Response Attributes for Awards in Claim Context

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:

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

Lockout Record Object

Lockout Policy Object

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:

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:

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:

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:

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:

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 for Retrieve Invalid Promo Codes Claimed by Customer

This method offers the following endpoints:

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 for Retrieve Invalid Promo Codes Claimed by Customer

The following parameters are available when specifying the endpoint for this method:

Request Object for Retrieve Invalid Promo Codes Claimed by Customer

Not applicable.

Response Object for Retrieve Invalid Promo Codes Claimed by Customer

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

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

Statuses and Errors for Retrieve Invalid Promo Codes Claimed by Customer

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.

Search Promo Codes by Criteria

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

Endpoints for Search Promo Codes by Criteria

This method offers the following endpoints:

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 for Search Promo Codes by Criteria

The following parameters are available when specifying the endpoint for this method:

Request Object for Search Promo Codes by Criteria

Not applicable.

Response Object for Search Promo Codes by Criteria

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

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

Response Attributes for Claim

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 for Search Promo Codes by Criteria

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.

Search by Promo Code

Filters for and retrieves data about a specific promo code.

Endpoints for Search by Promo Code

This method offers the following endpoints:

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 for Search by Promo Code

The following parameters are available when specifying the endpoint for this method:

Request Object for Search by Promo Code

Not applicable.

Response Object for Search by Promo Code

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:

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"
}

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

Statuses and Errors for Search by Promo Code

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:

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 for Cancel Promo Code

This method offers the following endpoints:

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 for Cancel Promo Code

The following parameters are available when specifying the endpoint for this method:

Request Object for Cancel Promo Code

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

JSON Request

{
    "codes": ["SOME_VALID_CODE", "SOME_INVALID_CODE"]
}

The array is detailed in the following table:

Request Attributes for Codes

Response Object for Cancel Promo Code

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

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

Statuses and Errors for Cancel Promo Code

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:

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