Coupon services

In scenarios where your discount coupons are handled outside of EVA, an integration is required for proper validations.

For that the whitelabel coupon handler settings come into play.

note

In instances where more than one coupon handler is used, we require a middleware where they are all grouped under. In turn our integration (coupon handler setting values) would point to that middleware.

Coupon handler settings

Using the Settings module of Admin Suite the following settings need to be configured:

Setting	Description
WhitelabelCouponHandler:BaseUrl	Base URL of the coupon handler.
WhitelabelCouponHandler:Username	The username to log in with.
WhitelabelCouponHandler:Password	The password to log in with.
WhitelabelCouponHandler:Timeout	Inactive time in minutes before a call is timed out. If this setting is not configured, a default value of 10 minutes would apply.

note

In order for EVA to instantiate the response body received by the handler API for consumption, EVA expects a .json format.

Here is a scenario to give you more context:

EVA will make the requests to the below three endpoints. Therefore, please configure those endpoints within your APIs as follows:

• BaseURL/GetDiscountCoupon
• BaseURL/RedeemDiscountCoupon
• BaseURL/ReleaseDiscountCoupon

The BaseURL to read as given in the corresponding setting (WhitelabelCouponHandler:BaseUrl) value, and .json request body as given in the below samples (one for each of those endpoints).

We also expect the body response to be .json and deserialized. Further, EVA will do basic authentication using the username and password provided in the settings (WhitelabelCouponHandler:Username and WhitelabelCouponHandler:Password) and will timeout after the given timeout as specified in the corresponding setting (WhitelabelCouponHandler:Timeout). If the timeout setting is not set/specified, the timeout will happen after 10 minutes (the default value).

Here are samples for each endpoint:

GetDiscountCoupon

Used to retrieve the coupon data.

baseurl/GetDiscountCoupon

{
  CurrencyID: “EUR”,         // Currency on which the coupon will be tried to redeem
  OrganizationUnitID: “bla”, // The organization unit BackendID on which the coupon is to be redeemed         
  CouponCode: “CP-1234-AB”,  // The coupon code
}

Response

{
  CanBeRedeemed: true,    // True / false if the coupon cannot be redeemed
  DiscountID: “blablabla” // The DiscountID which we will check against the discount BackendID in EVA to resolve a discount.
}

RedeemDiscountCoupon

Used to redeem/claim the coupon.

baseurl/RedeemDiscountCoupon

{
  CurrencyID: “EUR”,        // Currency context on which the coupon is redeemed
  OrganizationUnitID: “bla”,// The organization unit BackendID on which the coupon is redeemed
  DiscountID: “blablabla”,  // The DiscountID we received from GetDiscountCoupon 
  CouponCode: “CP-1234-AB”, // The coupon code
}

Response

{
  IsRedeemed: true,      // True / false if the coupon is redeemed
  RedeemID: “1231231AB”, // An identifier which we can use when a coupon is released through the ReleaseDiscountCoupon service
  CustomData: {}         // Optional custom data which we will send back when a coupon is released through the ReleaseDiscountCoupon service
}

ReleaseDiscountCoupon

Used to release/revert a claimed coupon.

baseurl/ReleaseDiscountCoupon

{
  CurrencyID: “EUR”,        // Currency context on which the coupon was redeemed
  OrganizationUnitID: “bla”,// The organization unit BackendID on which the coupon is redeemed
  DiscountID: “blablabla”,  // the discount BackendID on which the coupon was redeemed.
  CouponCode: “CP-1234-AB”, // The coupon code
  RedeemID: “1231231AB”,    // the RedeemID from the RedeemDiscountCoupon response
  CustomData: {}            // the optional custom data which we received in the RedeemDiscountCoupon response
}

Response

{
  IsReleased: true, // true / false if the coupon is released
}

note

The DiscountID provided in the response of GetDiscountCoupon is the property EVA will use to search among discounts, namely against discounts BackendID. A match means that the coupon discount has been identified in EVA.

Coupon discount configuration

Back at the Promotion engine chapter, a corresponding coupon discount should be configured whereas, in step 6/6 a link to the Whitelabel handler should be made as shown in the below screenshot.

tip

• Coupon codes do not need to be configured since those are pulled into EVA with each redeeming attempt made, hence making a link to the whitelabel in step 6/6 suffices this requirement.
• For traceability, any redeemed coupons will be displayed in the corresponding coupon discount, under coupons in the right sidebar. This includes the handlers name.

Event export

Once settings are in place, event exports can be used. In this scenario, the event contents would read as follows:

• Target: Coupon (ID: 19)
• EventType: Created
• Identifier: A GUID token. This token can then be used to resolve the coupon via the GetCouponByToken service.

Here is a sample GetCouponByToken response:

{
  Code = "TheCouponCode",
  UserID = 1,
  DiscountID = 1,
  DiscountDescription = "as configured",
  DiscountMarketingDescription = "as configured",
  ValidFrom = "as configured - day/month/year",
  ValidTill = "as configured - day/month/year"
}