To request a promo abuse recommendation when a customer attempts to apply a voucher, send a request to our Voucher endpoint using the Voucher Assessment checkpoint.
To use the Voucher Assessment checkpoint, add score=voucherAssessment as a query parameter to the URL.
The voucher object should contain details about the code the customer entered. Send one voucher per request.
Only send orderId if you will use the same orderId in your checkout request. This links the assessment to the order and redeemed voucher.
We strongly recommend sending all fields marked as important in the Voucher endpoint API reference. The more fields you can populate the better our recommendation. For REFERRAL vouchers, register the referral voucher when it is created. You do not need to send referrerId when requesting a recommendation.
An example request is shown below:
POST https://api.ravelin.com/v3/voucher?score=voucherAssessment HTTP/1.1
Authorization: token ...
Content-Type: application/json
{
"timestamp": 1512828988826,
"customer": {
"customerId": "customer-123",
"email": "jsmith123@example.com"
},
"voucher": {
"voucherCode": "20OFF",
"valueType": "PERCENTAGE",
"percentage": 20,
"maxDiscountValue": 1500,
"currency": "GBP",
"voucherType": "GENERAL"
},
"device": {
"deviceId": "device-123",
"ipAddress": "81.152.92.84"
},
"orderId": "order-987"
}An example response is shown below:
{
"action": "ALLOW",
"rules": {
"triggered": [
{
"ruleId": 1,
"ruleVersion": 1,
"action": "ALLOW",
"triggered": true,
"state": "active"
}
]
}
}The action field in the response contains our recommendation. You should either apply or reject the voucher depending on the action value.
The possible values are:
| Action | What it means |
|---|---|
ALLOW | We are confident this is a legitimate use of the voucher. Apply the discount. |
PREVENT | We are confident this is promo abuse. Do not apply the discount. Let the customer know the promotion is unavailable and allow them to continue at full price. |
If we have not seen the customer before, the response will include a customer-not-found warning. The customer is created when you register a referral voucher for them, or when you send a voucher redemption.
See the Voucher Endpoint API Reference for the full request and response format.
If you send a request to our Checkout endpoint using the Checkout Pre-auth checkpoint, rules in the Promo Abuse category can run alongside your other checkout rules.
If you are integrated with Payment Fraud, you may already be sending a Checkout request. Our recommendation at checkout will take into account all the types of fraud you are integrated to prevent. A separate voucher recommendation is not returned at checkout.
You should tell us each time a voucher is successfully redeemed. A recommendation is not a redemption: an ALLOW response, or a discount applied to a basket that is never paid for, is not counted as a use.
Only redemptions you send to us are counted when we assess future uses of the voucher in the customer’s network. Without them, our recommendations will be less accurate.
Send redemptions to the Payment Method Voucher endpoint, or include them in your Checkout request. If the voucher is redeemed outside checkout, for example when credit is added to the customer’s account, send it to the Payment Method Voucher endpoint. Since the voucher has already been applied, do not use the Voucher Assessment checkpoint.
Send each redemption once, either to the Payment Method Voucher endpoint or in your Checkout request, not both.
Use a paymentMethodId that is unique to each use of the voucher, such as the voucher code combined with the orderId. If the voucher is redeemed outside checkout, combine the code with another reference that is unique to that redemption.
An example request to the Payment Method Voucher endpoint is shown below:
POST https://api.ravelin.com/v2/paymentmethod/voucher HTTP/1.1
Authorization: token ...
Content-Type: application/json
{
"timestamp": 1512828988826,
"customerId": "abc-123-ZYZ",
"voucherRedemption": {
"paymentMethodId": "VOUCH-89-abc-123-ZYZ",
"voucherCode": "VOUCH-89",
"redemptionTime": 1512828988826,
"success": true,
"value": 10000,
"currency": "GBP",
"voucherType": "GENERAL"
}
}See the Payment Method Voucher Endpoint API Reference for the full request format.
Test your promo abuse integration
Was this page helpful?