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

1. Create a coupon in Yotpo Loyalty & Referrals.

2. Create redemption.

3. Create a coupon on your platform.

4. Your response - coupon created.

5. Cancel coupon API.

Create a coupon in Yotpo Loyalty & Referrals

1. In your Yotpo Loyalty & Referral main menu, go to Rewards > Redeeming Points.

2. Click on Create a New Coupon.

3. Select either Generic Variable or Generic Fixed Amount coupon type.

4. In the Create Coupons URL field, enter your URL for creating coupons on-demand.

5. Under 'Cancel Coupons URL' enter the URL for canceling old unused coupons. See Response - Coupon Created for more details. 

6. 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).

Payload example:

{
  "id": 113
}

Cancel coupon API

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"
}