Coupon activity

The coupon activity is used to buy, redeem or refund a coupon for a user. If the activity is successful then the API will return the ID of the activity. If one of the validation steps fails, then an error response with the appropriate exception is returned. See the Error Types & Responses SDK documentation for more information on error responses.

Supported actions

The coupon activities support the following types of actions:

• Buy: If the coupon has been configured to be bought with points and uses the two step redemption mode, then this will deduct the points from the user and award them the coupon. Following this action the coupon becomes available in the user's list of available coupons and can be redeemed.
• Redeem: If the coupon has been configured to be bought with points and uses the one step redemption mode, this will deduct the points from the user, award them the coupon and mark it as redeemed. If the coupon was already bought or was awarded without points, then it will be marked as redeemed.
• Refund: If the coupon was awarded without points and redeemed, then this will give the coupon back to the user. If the coupon was bought with points, then this will remove the coupon from the user and give them back the points.

For a detailed explanation of how the coupons can be configured and used, please refer to the Coupons section.

Error handling

Below are a list of errors which may be returned by the validation process when buying, redeeming or refunding a coupon:

• CouponNotFoundException: if the coupon code doesn't exist.
• CouponInactiveException: if the coupon code is inactive.
• CouponScarcityException: if the coupon has reached it's scarcity limit.
• CouponExpiredException: if the coupon has expired (both by date and by number of days since they were awarded).
• UserNotFoundException: if the user doesn't exist.
• CouponMemberException: if the user doesn't exist or is not a program member.

Buy and redeem specific errors

• CouponPointsException: for coupons which can be exchanged for points if the user doesn't have enough points in their balance to buy the coupon.
• CouponExpiredException: if the user has the coupon but it has expired by number of days since awarded.
• CouponRedeemedException: if the user has already redeemed the coupon code.
• CouponRedeemedOrExpiredException: if the user has multiple matching coupons but they are all redeemed or expired

Redeem specific errors

• CouponNotAwardedException: if the user hasn't been awarded the coupon code.

Buy specific errors

• CouponNotBuyableException: if coupon can't be bought with points or it has BuyRedeptionMode 'OneStep'.

Refund specific errors

• CouponRefundException: if the user has not used the coupon or it's not refundable.

Example

Here's an example of a coupon activity data that redeems a coupon:

JSON

var couponActivity = {
  uuid: "john@doe.com",
  url: "http://www.domain.com",
  attrs: {
    type: "coupon",
    action: "redeem",
    code: "COUPONCODE",
  },
};

In this example:

• The user is identified by the email 'john@doe.com'
• The action is 'redeem', which will mark the coupon as redeemed if available
• The code field specifies which coupon to redeem

Related topics

---

• Activities overview
• Coupons
• Points