Annex Cloud
/
Incentive Engine Management
/
Code Update

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

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

Update code details

Request

This API method facilitates both redemption and undo-redemption operations for incentive codes.

Bodyapplication/json
incentiveCodestringrequired

Enter the specific incentive code that has been redeemed by the member.

Example: "APPMFDTC"
userIdstringrequired

Enter the user ID of the member who has redeemed the incentive code.

Example: "user@domain.com"
codeValueinteger

Enter the unique value assigned to the incentive code that has been assigned to the member.

Example: 1
referenceId (Required if redemption process selected is with referenceID)string

Enter the unique variable used for the Redemption or Undo-Redemption operation. It is generated for each redemption or undo-redemption action, ensuring uniqueness every time it is utilized.

Example: "xyz01"
curl -i -X PATCH \
  'https://s15.socialannex.net/api/3.0/incentive/updatecodedetails/{{memberId}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "incentiveCode": "APPMFDTC",
    "userId": "user@domain.com",
    "codeValue": 1,
    "referenceId (Required if redemption process selected is with referenceID)": "xyz01"
  }'

Responses

successful operation

Body
messagestring

Displays the message shown upon redeeming the incentive code.

Example: "Incentive code redeemed successfully."
groupIdinteger

Displays the unique identifier assigned to a group of incentives. The Group ID is auto generated by Annex Cloud.

Example: 7820
sourcestring

Displays the origin or platform from which the incentive codes are being redeemed. It provides information about the source or channel through which the redemption activity occurred.

Example: "WEB"
userIdstring

Displays the user ID of the member who has redeemed the incentive code. It serves as a unique identifier for the member who initiated the redemption activity.

Example: "user@domain.com"
orderIdstring

Displays the order ID associated with the order for which the member redeemed the incentive code. It serves as a reference to the specific transaction or purchase that led to the redemption of the incentive code.

Example: "BB0547"
incentiveCodestring

Displays the specific incentive code that has been redeemed by the member.

Example: "APPMFDTC"
codeTypestring

Displays the privacy level of the redemption code. Public codes - These are openly accessible and can be redeemed by anyone. Private codes - These are restricted and can only be redeemed by specific users or within certain contexts.

Example: "Private"
codeValiditystring

Displays the specific date until which the code remains valid and can be redeemed in yyyy-mm-ddThh:mm:ss.

Example: "2020-12-18T12:46:18+0000"
codeStatusstring

Displays the status of the incentive code specifying whether it has been partially used or fully used. Partially Used - This status indicates that the incentive code has been partially redeemed, with a portion of its value or benefits utilized, while the remainder remains available for future use. Fully Used - This status indicates that the incentive code has been fully redeemed, with all of its value or benefits utilized, and no remaining balance available for further redemption.

Example: "Partially Used"
codeValueinteger

Displays the unique value assigned to the incentive code.

Example: 1
balanceCodeValueinteger

Displays the remaining balance value of the incentive code after deducting the entered code value from the total value of the incentive code. It provides members with information regarding the current available balance associated with the incentive code.

Example: 8
redemptionLimitinteger

Displays the redemption limit set for the member. It indicates the maximum number of times the member can redeem the incentive code.

Example: 5
redeemedinteger

Displays the number of times the incentive code has been redeemed by the member. It serves as a tally of the total number of redemption instances for the specific incentive code.

Example: 4
referenceIdstring

Displays the unique variable used for the Redemption or Undo-Redemption operation. It is generated for each redemption or undo redemption action, ensuring uniqueness every time it is utilized.

Example: "xyz01"
Response
{
  "message": "Incentive code redeemed successfully.",
  "groupId": 7820,
  "source": "WEB",
  "userId": "user@domain.com",
  "orderId": "BB0547",
  "incentiveCode": "APPMFDTC",
  "codeType": "Private",
  "codeValidity": "2020-12-18T12:46:18+0000",
  "codeStatus": "Partially Used",
  "codeValue": 1,
  "balanceCodeValue": 8,
  "redemptionLimit": 5,
  "redeemed": 4,
  "referenceId": "xyz01"
}

Update code configurations

Request

The API method is designed for updating incentive code details, including status and value. Note that the "value" parameter is relevant only for partial redemption types.

Bodyapplication/json
incentiveCodestringrequired

Enter the specific incentive code that is being updated.

Example: "APPMFDTC"
userIdstringrequired

Enter the user Id of the member for whom the incentive code is being updated.

Example: "user@domain.com"
codeStatusstring

Enter the status of the incentive code specifying whether it is Active or Inactive. Active- This status denotes that the code is currently enabled within the incentive engine management system. Members can successfully apply active codes to access associated incentives, rewards, or discounts. Inactive- This status indicates that the code has been disabled or temporarily suspended within the incentive engine management system. Inactive codes cannot be utilized by members to access benefits.

Example: "Active"
curl -i -X PATCH \
  'https://s15.socialannex.net/api/3.0/incentive/updatecodeconfig/{memberId}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "incentiveCode": "APPMFDTC",
    "userId": "user@domain.com",
    "codeStatus": "Active"
  }'

Responses

successful operation

Body
messagestring

Displays the message shown upon updating the incentive code.

Example: "code status updated Successfully."
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: 7820
sourcestring

Displays the origin or platform from which the incentive codes are being updated. It provides information about the source or channel through which the update activity occurred.

Example: "WEB"
userIdstring

Displays the user ID of the member for whom the incentive code is being updated.

Example: "user@domain.com"
incentiveCodestring

Displays the specific incentive code that has been updated for the member.

Example: "APPMFDTC"
codeTypestring

Displays the privacy level of the redemption code. Public codes - These are openly accessible and can be redeemed by anyone. Private codes - These are restricted and can only be redeemed by specific users or within certain contexts.

Example: "Private"
codeValiditystring

Displays the specific date until which the code remains valid and can be redeemed in yyyy-mm-ddThh:mm:ss.

Example: "2020-12-18T12:46:18+0000"
codeStatusstring

Displays the status of the incentive code specifying whether it is Active or Inactive. Active- This status denotes that the code is currently enabled within the incentive engine management system. Members can successfully apply active codes to access associated incentives, rewards, or discounts. Inactive- This status indicates that the code has been disabled or temporarily suspended within the incentive engine management system. Inactive codes cannot be utilized by members to access benefits.

Example: "Active"
codeValueinteger

Displays the unique value assigned to the incentive code.

Example: 1
Response
{
  "message": "code status updated Successfully.",
  "groupId": 7820,
  "source": "WEB",
  "userId": "user@domain.com",
  "incentiveCode": "APPMFDTC",
  "codeType": "Private",
  "codeValidity": "2020-12-18T12:46:18+0000",
  "codeStatus": "Active",
  "codeValue": 1
}

Update batch code details

Request

This API method facilitates the deduction of an amount from multiple gift cards or store credits. (It is designed to handle multiple redemption and undo redemption operations.)

Bodyapplication/json
incentiveCodestringrequired

Enter the incentive code that is redeemed by the member.

Example: "XhEwN"
userIdstringrequired

Enter the user ID of the member who has redeemed the incentive code. It serves as a unique identifier for the member who initiated the redemption activity.

Example: "user@domain.com"
codeValuestring

Enter the unique value assigned to the incentive code.

Example: "1"
referenceIdstring

Enter the unique variable used for the Redemption or Undo-Redemption operation. It is generated for each redemption or undo-redemption action, ensuring uniqueness every time it is utilized. (Note -\ Required if redemption process has been selected with reference Id.)

Example: "xyz01"
curl -i -X PATCH \
  'https://s15.socialannex.net/api/3.0/incentive/updatebatchcodedetails/{{siteId}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "incentiveCode": "XhEwN",
    "userId": "user@domain.com",
    "codeValue": "1",
    "referenceId": "xyz01"
  }'

Responses

successful operation

Body
messagestring

Displays the message shown upon redeeming the incentive code.

Example: "Incentive code redeemed successfully."
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"
groupIdinteger

Displays the unique identifier assigned to a 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
sourcestring

Displays the origin or platform from which the incentive codes are being redeemed. It provides information about the source or channel through which the redemption activity occurred.

Example: "WEB"
userIdstring

Displays the user ID of the member who has redeemed the incentive codes. It serves as a unique identifier for the member who initiated the redemption activity.

Example: "user@domain.com"
orderIdinteger

Displays the order ID associated with the order for which the member redeemed the incentive code. It serves as a reference to the specific transaction or purchase that led to the redemption of the incentive code.

Example: "BB0547"
incentiveCodestring

Displays the specific incentive code that has been redeemed by the member. It serves as a unique identifier for the incentive associated with the member's redemption activity.

Example: "XhEwN"
codeTypestring

Displays the privacy level of the redemption code. Public codes - These are openly accessible and can be redeemed by anyone. Private codes - These are restricted and can only be redeemed by specific users or within certain contexts.

Example: "Private"
codeStatusstring

Displays the status of the incentive code specifying whether it has been partially used or fully used. Partially Used - This status indicates that the incentive code has been partially redeemed, with a portion of its value or benefits utilized, while the remainder remains available for future use. Fully Used - This status indicates that the incentive code has been fully redeemed, with all of its value or benefits utilized, and no remaining balance available for further redemption.

Example: "Partially Used"
codeValueinteger

Displays the unique value assigned to redemption code.(This value can be used for full or partial redemption).

Example: 1
balanceCodeValueinteger

Displays the remaining balance value of the incentive code after deducting the entered code value from the total value of the incentive code. It provides users with information regarding the current available balance associated with the incentive code.

Example: 8
redemptionLimitinteger

Displays the redemption limit set for the member. It indicates the maximum number of times the member can redeem the incentive code.

Example: 5
redeemedinteger

Displays the number of times the incentive code has been redeemed by the member. It serves as a tally of the total number of redemption instances for the specific incentive code.

Example: 1
referenceIdstring

Displays the unique variable used for both the Redemption and Undo Redemption operations. It is generated for each redemption or undo redemption action, ensuring uniqueness every time it is utilized.

Example: "xyz01"
Response
{
  "message": "Incentive code redeemed successfully.",
  "siteId": "9991331",
  "groupId": 8417,
  "source": "WEB",
  "userId": "user@domain.com",
  "orderId": "BB0547",
  "incentiveCode": "XhEwN",
  "codeType": "Private",
  "codeStatus": "Partially Used",
  "codeValue": 1,
  "balanceCodeValue": 8,
  "redemptionLimit": 5,
  "redeemed": 1,
  "referenceId": "xyz01"
}

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