Annex Cloud
/
Incentive Engine Management
/
Incentive Codes

Incentive Engine V3 APIs (3.0.1)

Annex Cloud’s Incentive Engine helps to create rewards that can be used as marketing incentives by businesses either with loyalty programs or without loyalty programs. The benefits of these types of incentives could include a certain percentage off on a purchase or a specific amount discount. This type of incentive engine is used to attract and retain customers.

Annex Cloud incentive engine offers two types of redemptions- Full Redemption & Partial Redemption

Full Redemption- Full redemption yields the reward points on a comprehensive basis. The redeemed incentives can offer discounts as a percentage or in the form of a fixed rate coupon. The format of the rewards can be provided as coupon codes and voucher codes.

Partial Redemption- A partial redemption allows rewards to be redeemed in portions - leaving the rest available to be redeemed later. This includes a redemption of rewards in the form of gift cards and store cards.

Download OpenAPI description
iem.json
iem.yaml
Languages
Servers

https://s15.socialannex.net/api/3.0/

Incentive Codes

The Annex Cloud Incentive Engine empowers businesses to create marketing rewards, whether or not they have loyalty programs. These rewards, which may offer discounts on purchases, are redeemable in full or partially. Coupon and voucher codes are used for full redemption, while gift and store cards are for partial redemption. This API enables the creation of both full and partial redemption incentive codes, using a POST request method that is POST - /incentive/codes

Operations

This API facilitates the generation of both full and partial

Request

Bodyapplication/json
redemptionTypeintegerrequired

Enter the redemption method for which an incentive is redeemed. It allows users to specify whether the redemption process will be full or partial. Use 0 to indicate full redemption, where the entire incentive is redeemed. Use 1 to indicate partial redemption, where only a portion of the incentive is redeemed, with the remaining balance retained for future use.

Example: 1
statusintegerrequired

Enter the current state of the incentive within the incentive engine management system. Active (0)- The incentive is fully active and available for use. Inactive (1)- The incentive is currently inactive and unavailable for use.

Example: 0
codeTypeintegerrequired

Enter the privacy level of the redemption codes generated. 0 indicates public codes, which are openly accessible and can be redeemed by anyone. 1 indicates private codes, which are restricted and can only be redeemed by specific customers or within certain contexts.

Example: 1
partialTypeintegerrequired

Enter the value of a partial redemption for an incentive. Different partial type codes are Store Credit (1), Gift card (2), Discount Amount (6), Discount Percentage (7), Free Product (8), Product with Discount Amount (9), Product with Discount Percentage (10).

Example: 1
startDatestringrequired

Enter the date and time when the incentive becomes effective in yyyy-MM-dd'T'HH:mm:ssZ format. It marks the beginning of the period during which the incentive is valid and can be utilized.

Example: "2018-04-01T00:00:00-0700"
endDatestring

Enter the date and time when the incentive becomes ineffective in yyyy-MM-dd'T'HH:mm:ssZ format. It marks the end of the period after which the incentive is invalid and cannot be utilized.

Example: "2025-04-01T00:00:00-0700"
codeValuesintegerrequired

Enter the unique values assigned to redemption codes generated within the incentive engine management system. The value of each code is represented by "n", where "n" is the numerical value assigned to the code. In cases where partial redemption is enabled and codes are generated in fixed groups, only four distinct code values can be generated within each group. (Required in the case of Partial Redemption).

Example: 0
codeLengthintegerrequired

Enter the length of the redemption code associated with an incentive.

Example: 6
noOfCodesintegerrequired

Enter the quantity of redemption codes to be generated within the incentive engine management system. For Dynamic Group Creation - Set the number of codes to 0, indicating that the creation of codes will be dynamic, and the system will handle the generation process automatically. If the number of codes exceeds 10,000, the generation process will occur in the background.

Example: 0
codeCharsetstring

Enter the format used in the redemption code. These are the different formats - Numeric (0) - Only numeric characters are used in the redemption code. Alphanumeric (1)- Both numeric and alphabetic characters (lowercase and uppercase) are used in the redemption code. Alphabet with Lowercase (2)- Only lowercase alphabetic characters are used in the redemption code. Alphabet with Uppercase (3)- Only uppercase alphabetic characters are used in the redemption code.

Example: "3"
prefixstring

Enter the string of characters that are appended at the beginning of each redemption code generated.

Example: "A"
postfixstring

Enter the string of characters that are appended at the end of each redemption code generated.

Example: "C"
curl -i -X POST \
  https://s15.socialannex.net/api/3.0/incentive/codes \
  -H 'Content-Type: application/json' \
  -d '{
    "redemptionType": 1,
    "status": 0,
    "codeType": 1,
    "partialType": 1,
    "startDate": "2018-04-01T00:00:00-0700",
    "endDate": "2025-04-01T00:00:00-0700",
    "codeValues": 0,
    "codeLength": 6,
    "noOfCodes": 0,
    "codeCharset": "3",
    "prefix": "A",
    "postfix": "C"
  }'

Responses

successful operation

Body
siteIdstring

Displays the unique identifier assigned to a specific site. It is used to distinguish between different sites where the incentives are applicable.

Example: "9991331"
messagestring

Displays the message that will be displayed to the user once the incentive codes are generated.

Example: "Codes generated successfully"
redemptionTypeinteger

Displays the method in which the incentive is redeemed. 0 indicates full redemption, where the entire incentive is redeemed. 1 indicates partial redemption, where only a portion of the incentive is redeemed, with the remaining balance retained for future use.

Example: 1
groupNamestring

Displays the name assigned to a group of incentives. It facilitates organization and categorization of incentives based on common characteristics, such as campaign, product, or target audience.

Example: "IE_20240227_8417"
statusinteger

Displays the current state of the incentive. 0 indicates the incentive is fully active and available for use. 1 indicates the incentive is currently inactive and unavailable for use.

Example: 0
codeTypeinteger

Displays the privacy level of the redemption codes generated. 0 indicates public codes, which are openly accessible and can be redeemed by anyone. 1 indicates private codes, which are restricted and can only be redeemed by specific users or within certain contexts.

Example: 1
partialTypeinteger

Displays the value of a partial redemption for an incentive that is taking place. Different partial type codes are Store Credit (1), Gift card (2), Discount Amount (6), Discount Percentage (7), Free Product (8), Product with Discount Amount (9), Product with Discount Percentage (10).

Example: 1
startDatestring

Displays the date and time when the incentive becomes effective in yyyy-MM-dd'T'HH:mm:ssZ format. It marks the beginning of the period during which the incentive is valid and can be utilized.

endDatestring

Displays the date and time when the incentive becomes ineffective in yyyy-MM-dd'T'HH:mm:ssZ format. It marks the end of the period after which the incentive is invalid and cannot be utilized.

codeValuesinteger

Displays the unique values assigned to redemption codes generated within the incentive engine management system.

Example: 0
codeLengthinteger

Displays the length of the redemption code generated that associated with an incentive.

Example: 6
noOfCodesinteger

Displays the quantity of redemption codes to be generated within the incentive engine management system.

Example: 0
codeCharsetinteger

Displays the format used in the redemption code. These are the different formats - Numeric (0) - Only numeric characters are used in the redemption code. Alphanumeric (1)- Both numeric and alphabetic characters (lowercase and uppercase) are used in the redemption code. Alphabet with Lowercase (2)- Only lowercase alphabetic characters are used in the redemption code. Alphabet with Uppercase (3)- Only uppercase alphabetic characters are used in the redemption code.

Example: 3
prefixstring

Displays the string of characters that are appended at the beginning of each redemption code generated.

Example: "A"
postfixstring

Displays the string of characters that are appended at the end of each redemption code generated.

Example: "C"
groupIdinteger

Displays the unique identifier assigned to the group of incentives. The Group ID is auto generated by Annex Cloud. It allows administrators to categorize and organize incentives based on common characteristics such as campaign, product, or target audience.

Example: 8417
Response
{
  "siteId": "9991331",
  "message": "Codes generated successfully",
  "redemptionType": 1,
  "groupName": "IE_20240227_8417",
  "status": 0,
  "codeType": 1,
  "partialType": 1,
  "startDate": "string",
  "endDate": "string",
  "codeValues": 0,
  "codeLength": 6,
  "noOfCodes": 0,
  "codeCharset": 3,
  "prefix": "A",
  "postfix": "C",
  "groupId": 8417
}

Code Assign

The Annex Cloud Incentive Engine empowers businesses to create marketing rewards, whether or not they have loyalty programs. These rewards, which may offer discounts on purchases, are redeemable in full or partially. Coupon and voucher codes are used for full redemption, while gift and store cards are for partial redemption.

This API is used to assign incentive codes to members. The API for Code Assign uses the POST request method to assign incentive codes. POST - /incentive/assigncodes

Operations

Code Validity

The Annex Cloud Incentive Engine empowers businesses to create marketing rewards, whether or not they have loyalty programs. These rewards, which may offer discounts on purchases, are redeemable in full or partially. Coupon and voucher codes are used for full redemption, while gift and store cards are for partial redemption.

This API method is used to check the validity of the incentive code assigned to the member. GET - /incentive/validatecode/incentiveCode

Operations

Code Update

The Annex Cloud Incentive Engine empowers businesses to create marketing rewards, whether or not they have loyalty programs. These rewards, which may offer discounts on purchases, are redeemable in full or partially. Coupon and voucher codes are used for full redemption, while gift and store cards are for partial redemption.

These API methods utilize the PATCH request method to modify code redemption status, code configuration, and batch details for the site. PATCH - /incentive/updatecodedetails/userId, PATCH - /incentive/updatecodeconfig/userId & PATCH - /incentive/updatebatchcodedetails/siteId

Operations

User Code Details

The Annex Cloud Incentive Engine empowers businesses to create marketing rewards, whether or not they have loyalty programs. These rewards, which may offer discounts on purchases, are redeemable in full or partially. Coupon and voucher codes are used for full redemption, while gift cards and store cards are for partial redemption.

These API methods are used to get details of the codes assigned to a member. POST - /incentive/usercodedetails & GET - /incentive/usercodedetails/{{userId}}

Operations

Bulk Assignment

The Annex Cloud Incentive Engine empowers businesses to create marketing rewards, whether or not they have loyalty programs. These rewards, which may offer discounts on purchases, are redeemable in full or partially. Coupon and voucher codes are used for full redemption, while gift and store cards are for partial redemption. POST:/incentive/bulkassignment

Operations

Redemption Log

The Annex Cloud Incentive Engine empowers businesses to create marketing rewards, whether or not they have loyalty programs. These rewards, which may offer discounts on purchases, are redeemable in full or partially. Coupon and voucher codes are used for full redemption, while gift cards and store cards are for partial redemption.

This API retrieves details of redemption and undo redemption actions, offering counts of successful redemption or undo redemption requests. The counts can be provided for all requests within a specified period, or specific to each customer ID or voucher (code) ID. POST - /incentive/getredemptionlog

Operations

Get All Incentive Groups

The Annex Cloud Incentive Engine empowers businesses to create marketing rewards, whether or not they have loyalty programs. These rewards, which may offer discounts on purchases, are redeemable in full or partially. Coupon and voucher codes are used for full redemption, while gift cards and store cards are for partial redemption.

This API method retrieves the details of the incentive code group, utilizing the GET request method to fetch information pertaining to the group. GET - /incentive/getincentivegroup/groupId & GET - /incentive/getallincentivegroups/all

Operations