Validate rewards redemption

Check the complete list of parameters and responses of the PUT redeem/preview endpoint to preview or validate rewards redemptions.

Overview

When you want to emit a purchase event that contains rewards redemptions, you may want 2 things before emitting the event:

Preview the rewards redemptions: This allows your customers to be sure what they are going to redeem before they actually redeem it.
Validate the rewards redemptions: This allows you to check if the rewards redemptions are valid and can be redeemed.

Why do we need to check if a redemption is valid?

Every type of reward have different rules to follow in order to be redeemed. POINTS: Can be redeemed at any level, this is the reward type that is most flexible. DISCOUNT: Discounts when created are configured to work on a specific entity, like a product, the shipping cost, or the order value. When redeeming a discount, you need to set the discount at the same entity that was configured. PRODUCT: Either ADD or REPLACE product rewards must only be redeemed at the order level. This is because adding a product that doesn’t exist or replacing a product for another one, you wouldn’t have a place to set the rewards to be redeemed. GIFT CARD: Gift cards are redeemed using only the redeem gift card endpoints. Redeeming a gift card in a purchase event will not work. Additionally, each reward may have some conditions configured to be met in order to be redeemed. For example, a discount may have a minimum order value to be redeemed.

Preview rewards redemptions

To preview rewards redemptions, you need to send a PUT request to the redeem/preview endpoint. The endpoint will send back the exact order you originally sent, but with an additional keyword redemptions_result at each level where a redeem array was found. The endpoint doesn’t want to force you how to present the data to the customer, it just provide the data you need to build whatever experience you want to show.

Example Order sent

Let’s pretend we want to preview the rewards redemptions for the following order:

{
  "order": {
    "products": [
      {
        "sku": "123",
        "amount": 1,
        "value": 10,
        // Rewards to be redeemed at the product level
        "redeem": [
          {
            "reward_id": "<points-id>",
            "amount": 6 // Assume a conversion factor of 1
          }
        ]
      }
    ],
    "shipping": {
      "value": 2
    },
    "value": 12
  }
}

Example Order received

The response will be the same order you sent, but with the rewards redemptions previewed:

{
  "order": {
    "products": [
      {
        "sku": "123",
        "amount": 1,
        "value": 10,
        "redeem": [
          {
            "reward_id": "<points-id>",
            "amount": 6
          }
        ],
        "redemptions_result": {
          "redeemed": [
            {
              "id": "<points-id>",
              "action": "UPDATE",
              "amount": 6,
              "reward": {
                /* reward data */
              }
            }
          ],
          "value": 4,
          "amount": 1,
          "discount_value": 6,
          "discount_percent": 0.6,
          "action": "UPDATE"
        }
      }
    ],
    "shipping": {
      "value": 2
    },
    "value": 12,
    "redemptions_result": {
      "redeemed": [],
      "value": 6,
      "amount": 1,
      "discount_value": 6,
      "discount_percent": 0.5,
      "action": "UPDATE"
    }
  },
  "redemption_steps": [
    {
      "reward_id": "<points-id>",
      "reward_amount": 6,
      "target": "product",
      "target_id": "123",
      "action": "UPDATE",
      "discount_value": 6,
      "before": {
        "value": 12,
        "amount": 1,
        "discount_value": 0,
        "discount_percent": 0
      },
      "after": {
        "value": 6,
        "amount": 1,
        "discount_value": 6,
        "discount_percent": 0.5
      },
      "target_before": {
        "value": 10,
        "amount": 1,
        "discount_value": 0,
        "discount_percent": 0
      },
      "target_after": {
        "value": 4,
        "amount": 1,
        "discount_value": 6,
        "discount_percent": 0.6
      }
    }
  ]
}

Several things happened in the response:

The redemptions_result object was to the product that redeemed 6 points.
This new object contains the discounted value of the product value, how much was discounted discount_value, the percentage of the discount discount_percent. This values can be used to show the customer how much they are saving.
It also contains an action field that tells you what to do with the affected entity:
- UPDATE: The entity was updated, display these values instead.
- READ: The entity has been updated before, but the last redeem didn’t change anything.
- DELETE: Then entity was removed, don’t display this item in the order.
- CREATE: The entity is new and must be display along the other products in the order.
The redeemed array contains the rewards that were redeemed and the action that was taken.
Even though we redeemed a reward at the product level, a redemption_result was created at the order level as well. This is because the order level was affected by the redemption.
redemption_steps records every redemption in application order. before and after show how the order changed. Product and shipping steps also include target_before and target_after for the affected item.

How `value`, `discount_value` and `discount_percent` are calculated

Rewards are applied one by one, in the same order as the redeem array. Each redemption builds on top of the previous redemptions_result of the entity, so the fields always accumulate across all redeemed rewards:

POINTS: discounts amount × conversion_factor from the entity value. The accumulated discount is capped at the entity value, so value never goes negative.
DISCOUNT (fixed): discounts discount_value × amount from the entity value.
DISCOUNT (percentage): the percentage is applied over the remaining value (after previous redemptions). This means the order of the redeem array matters for percentage discounts: a 50% discount applied after a $2 discount is smaller than one applied before it.
PRODUCT (ADD_PRODUCT / REPLACE_PRODUCT): adds estimated_value × replace_amount (or new_amount for additions) to discount_value, but does not reduce the entity value. The saving is an estimate: the customer pays the same for the rest of the order and receives the added/replaced product for free.

This is what each field means after all redemptions are applied:

value: what the entity costs after applying the value-reducing rewards (POINTS and DISCOUNT). This is the field to use when validating the amount to charge.
discount_value: the total accumulated saving from all redeemed rewards, including the estimated value of PRODUCT rewards. Because PRODUCT rewards don’t reduce value, value + discount_value can be greater than the original entity value.
discount_percent: the percentage that the value-reducing rewards represent over the original entity value, capped at 1. PRODUCT rewards don’t change it (it keeps the previous percentage, or null if there is none), so when PRODUCT rewards are redeemed discount_percent will not equal discount_value divided by the original value.
redemption_steps[].discount_value: the saving contributed by that individual redemption to the order total. Failed or fully capped redemptions contribute 0.
redemption_steps[].before.discount_percent and redemption_steps[].after.discount_percent: the cumulative saving divided by the original order value, capped at 1. These step percentages include the estimated value of PRODUCT rewards.

redemption_steps is chronological across the whole preview: product redemptions are applied first in product order, then shipping redemptions, and finally order redemptions. Within each target, entries follow the original redeem array order. Use target to map the contribution to an external code—for example, shipping to a delivery discount code and order or product to the corresponding merchandise discount code. before and after always show the cumulative order state. target_before and target_after are only present for product and shipping steps, where the affected target differs from the order. For example, on a

106.25 order redeeming a 50% order discount plus a REPLACE_PRODUCT reward with an `estimated_value` of

2.34, the existing order-level result remains value: 53.125, discount_value: 55.465 and discount_percent: 0.5. In redemption_steps, the first reward leaves after.discount_percent at 0.5 and the product reward raises it to 0.5220235294117647 (55.465 / 106.25).

Example Order with an error

Some rewards may have conditions that need to be met in order to be redeemed. If the conditions are not met, the rewards will not be redeemed. Take into consideration that the response will end with a status of 200. You will need to display the error to the customer.

{
  "order": {
    "products": [
      {
        "sku": "123",
        "amount": 1,
        "value": 10,
        "redeem": [
          {
            "reward_id": "<discount-id>",
            "amount": 6
          }
        ],
        "redemptions_result": {
          "redeemed": [
            {
              "id": "<discount-id>",
              "action": "READ",
              "amount": 1,
              "reward": {
                /* reward data */
              },
              "error": "Cannot redeem a shipping discount on a product"
            }
          ],
          "value": 10,
          "amount": 1,
          "discount_value": 0,
          "discount_percent": 0,
          "action": "READ"
        }
      }
    ],
    "shipping": {
      "value": 2
    },
    "value": 12
  },
  "redemption_steps": [
    {
      "reward_id": "<discount-id>",
      "reward_amount": 6,
      "target": "product",
      "target_id": "123",
      "action": "READ",
      "discount_value": 0,
      "before": {
        "value": 12,
        "amount": 1,
        "discount_value": 0,
        "discount_percent": 0
      },
      "after": {
        "value": 12,
        "amount": 1,
        "discount_value": 0,
        "discount_percent": 0
      },
      "target_before": {
        "value": 10,
        "amount": 1,
        "discount_value": 0,
        "discount_percent": 0
      },
      "target_after": {
        "value": 10,
        "amount": 1,
        "discount_value": 0,
        "discount_percent": 0
      },
      "error": "Cannot redeem a shipping discount on a product"
    }
  ]
}

In this case, the discount was not redeemed because it was a shipping discount and it was redeemed at the product level. A new field error was added to the redeemed object. This error can either be shown to the customer or used to debug your implementation.

Re-validating an order

Many things may happen that will force you to update an order. For example: adding/removing products, applying/removing a reward, updating an item amount, changing the delivery address, etc. After each of these situations, you will need to re-validate the order. When revalidating the order you must keep a copy of your original products and values. Do not replace them with the ‘redemptions_result’ object. This data should only be used to help your customers preview the rewards redemptions. Use the action field to know what to do with the entity. If you are re-validating an order, it is super important to also bring with you the ‘redemptions_result’ object of each entity. Masivo will use these objects to know what rewards to redeem next, which rewards were already redeemed, and which rewards were removed.