Check whether a single-use coupon code is valid and return details about the reward it is allowed to be redeemed for.
In this case we assume that Mention Me has issued a coupon to a customer or potential customer. This coupon could be a single-use coupon previously given to Mention Me in a batch of coupons. Or it could be a single-use coupon generated directly by Mention Me.
The customer could have been promised the reward as a potential new customer (referee), for referring another customer (referrer) or just because they've been offered an incentive to come to store (incentive for action).
The customer then brings the coupon to the merchant intending to redeem it. This endpoint allows the merchant (or a third party) to check if the coupon is still valid and is capable of being used to redeem a reward at Mention Me.
This endpoint allows you to validate a coupon code before attempting to redeem it. It will check:
-
Whether the coupon exists for your merchant
-
Whether the coupon is currently valid (not expired, not barred, has started)
-
Whether the coupon is attached to an unredeemed reward and hence can be spent
There are three responses (validityResponseCode):
-
FOUND_REDEEMABLE - this means the coupon is found, is valid and can be used to spend the provided reward.
-
FOUND_NOT_REDEEMABLE - this means the coupon is known to Mention Me - but is either not valid or has already been spent.
-
NOT_FOUND - the coupon is not known to Mention Me.
There is also a human-readable description of the response code (validityResponseDescription). Use the validityResponseCode to decide on the outcome (the human-readable description could change).
If the coupon is found, the response will include details about the reward such as the discount amount, type (e.g., percentage or fixed amount), currency, and description.
If the coupon is not redeemable, the validityResponseDescription will indicate why it cannot be used.
If the coupon is not found, the response won't have additional details.
If you find the coupon is valid and then allow the customer to redeem the coupon you should then subsequently tell us about the purchase they made, including the coupon code so that we can mark it as redeemed. Once you've done that the coupon will of course be invalid if requested again.
You can do this using the Record Order API endpoint (if you have the email address of the customer) or the Redeem Coupon API endpoint (if you don't have the email address of the customer).
Scopes: customers:read, rewards:read
Rate limits: 100 requests per 5 minutes. Shared across all 'coupons' endpoints.