Implementing Redemptions via API
Implementing Redemptions via API is part of Implementing Loyalty & Referrals on a Custom or Generic eCommerce Platform. Redemption via API allows you to create both generic variable and generic fixed amount rewards on your generic/custom platform, as opposed to pre-uploading lists of coupon codes (as is required in the custom coupon option.)
Workflow for Implementing Redemptions via API
Create a coupon in Yotpo Loyalty & Referrals.
Create redemption.
Create a coupon on your platform.
Your response - coupon created.
Cancel coupon API.
Create a coupon in Yotpo Loyalty & Referrals
In your Yotpo Loyalty & Referral main menu, go to Rewards > Redeeming Points.
Click on Create a New Coupon.
Select either Generic Variable or Generic Fixed Amount coupon type.
In the Create Coupons URL field, enter your URL for creating coupons on-demand.
Under 'Cancel Coupons URL' enter the URL for canceling old unused coupons. See Response - Coupon Created for more details.
Enter the Secret key with which we will authenticate the request.
Please note:
The secret is passed both in the request header and request body.
The custom header is sent like this:
X-Api-Secret: my_secret
Create redemption
If you are using the Checkout On-site Module, you can skip this and proceed to the next step "Create Coupon on Your Platform."
If you're not using the checkout module, continue here:
When a customer redeems their points for a discount, the storefront/modules need to send the API call in this documentation to create a redemption (so if you’re using our Checkout On-site Module, you don’t need to implement this.)
https://loyaltyapi.yotpo.com/reference/create-redemption
Example of API call:
POST: https://loyalty.yotpo.com/api/v2/redemptions?merchant_id=1111&api_key=123
{
"coupon_code": "YW74IFB8",
"discount_amount": 10,
"discount_amount_cents": 1000,
"currency": "USD",
"customer_email": "test@yotpo.com"
}
Point deduction
Points should be deducted from the customer's account when we receive the order with the coupon code, not when creating the coupon. This is known as Delayed Point Deduction.
In your API call that creates the redemption, you need to include "delay_point_deduction": true
. If you don't include this parameter, the default is false and the points will be deducted immediately.
Create the coupon on your platform
Loyalty & Referrals generates the coupon code and sends you a request to create a coupon with this code for a specific discount amount.
Example:
{
"secret": "a1b2c3",
"coupon_code": "YW74IFB8",
"discount_amount": 10,
"discount_amount_cents": 1000,
"currency": "USD",
"customer_email": "test@yotpo.com"
}
Response - Coupon Created
If the coupon was created successfully on the platform, you should respond with a 200 OK and a JSON payload with the platform coupon id. This coupon id will be used in case we need to cancel old unused coupons (for fraud prevention).
Please note:
If the platform coupon ID is missing the redemption will fail, and a failed response will be sent to the platform and the original requester (which is either your website or one of the Loyalty & Referrals modules.)
Payload example:
{
"id": 113
}
Cancel coupon API
Please note:
For those not using Checkout On-site Module:
If you wish to use delayed point deduction, you need to include "delay_point_deduction": true in your create redemption API call. If you don't include this parameter, the default is false and the points will be deducted immediately.
If you are using the Checkout On-site Module, delayed point deduction is already built in.
If you are using the Checkout On-site Module or if you are using delayed point deduction, you will need to cancel the coupon on the platform in order to prevent tech-savvy users from fraudulently creating multiple coupons.
When a redemption request is received, we check if there is an old unused coupon for the customer and send an API call to cancel it on the platform.
We send the secret and platform coupon id (that was returned to us when the coupon was created on the platform) to the URL in the Cancel Coupons URL field.
Example:
{
"coupon_id": 1214,
"secret": "a1b2c3"
}