Reward-points Tutorial

With the Emporix API Reward Points Service, you can allow your customers to gather reward points for every completed order, or grant points to customers irrespective of the orders they made. Later on, the customers can exchange the collected points for coupons, which are managed through the Coupon Service, and can be added to a cart.

How to manage the reward points settings for a site

To start using the reward points functionality, first you need to update the reward points configuration for your site.

Retrieve the current reward points configuration for a site

Check the current reward points mixin configuration for your site by calling the Retrieving site mixins endpoint.

The following scope is required: site.site_manage.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -i -X GET 
  'https://api.emporix.io/site/{tenant}/sites/{siteCode}/mixins' 
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Update the reward points settings for a site

The reward points settings are stored in a site's mixins, within the coupon settings.

To learn more about mixins in the Emporix Commerce Engine, check out the Standard practices.

The parameters that need to be configured for the reward points are as follows:

• enable toggle - a boolean that indicates if the reward points feature is enabled

• orderValueToRewardPointsFactor - allows to calculate the number of reward points assigned to a customer after a purchase is made

• validityInMonths - specifies the lifespan of reward points

• couponPrefix - used to begin the coupon code generated at the moment of the reward points redemption, where the full coupon code with prefix is presented in the following format: prefix-coupon_code, for example L-232394

To update the reward points settings, send a request to the Partially updating a site mixin endpoint.

The following scope is required: site.site_manage.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -i -X PATCH 
  'https://api.emporix.io/site/{tenant}/sites/{siteCode}/mixins/{mixinName}' 
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' 
  -H 'Content-Type: application/json' 
  -d '{
    "active": true
  }'

How to manage reward points by an employee

As a merchant employee, you can manage your customers' reward points and redemption options.

Add reward points for a customer

If the reward points functionality is enabled, the reward points entry is created or updated for a customer automatically every time an order is completed.

The communication between reward points and site settings is cached. The cache is invalidated every 15 minutes. It has to be considered after modifying the configuration of reward points in site's mixins.

You can also manually add reward points for a customer by sending a request to the Adding reward points for a customer endpoint.

The following scope is required: rewardspoints.rewardpoints_manage.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -i -X POST 
  'https://api.emporix.io/reward-points/customer/{customerId}/addPoints?siteCode=main' 
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' 
  -H 'Content-Type: application/json' 
  -d '{
    "id": "12345fee-0b83-48aa-95dc-11e3dcf84aaa",
    "reference-id": "123456",
    "description": "points added",
    "points": 123,
    "createdAt": "2023-10-24T14:15:22Z",
    "allPointsAfterCreation": 56778,
    "usedPoints": 5,
    "validUntil": "2029-08-24T14:15:22Z",
    "usedWith": [
      "5237bcac-c548-4e49-8626-03dab65376d6"
    ]
  }'

Create reward points redemption options

As a merchant's employee, you can create a list of options for the customers to choose from when redeeming the collected reward points. For example, different types of coupons can be specified. To achieve that, you must send a request to the Creating redemption options endpoint.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -i -X POST 
  'https://api.emporix.io/reward-points/{tenant}/redeemOptions' 
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' 
  -H 'Content-Type: application/json' 
  -d '{
    "type": "coupon",
    "name": "10 Euro Gutschein",
    "description": "Für 90 Punkte können Sie sich einen Gutschein über 10 Euro generieren lassen. Diesen Gutschein können Sie auch an Freunde und Bekannte weitergeben.",
    "points": 90,
    "coupon": {
      "name": "Gutschein über 10 Euro (eingelöste Bonuspunkte)",
      "description": "Gutschein über 10 Euro aus 1000 Bonuspunkte",
      "discountType": "ABSOLUTE",
      "discountAbsolute": {
        "amount": 10,
        "currency": "EUR"
      },
      "allowAnonymous": true,
      "maxRedemptions": 1,
      "status": "VALID"
    }
  }'

How to manage the reward points by a logged-in customer

Your customers can redeem the collected reward points by paying with coupons that are generated based on the number of collected points.

Check the available reward points redemption options

If the customer wants to redeem reward points in exchange for a coupon, first they need to check the available coupon options offered by the merchant. To achieve that, they need to send a request to the Retrieving redemption options endpoint on the storefront.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -i -X GET 
  'https://api.emporix.io/reward-points/{tenant}/redeemOptions' 
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Redeem reward points for a coupon code

To create a coupon based on a certain amount of reward points, the customer sends a request to theRedeeming a logged-in customer's reward points for a coupon code endpoint on the storefront.

Reward points can only be exchanged for percentage and absolute coupons.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -i -X POST 
  'https://api.emporix.io/reward-points/public/customer/redeem?siteCode=main' 
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' 
  -H 'Content-Type: application/json' 
  -d '{
    "id": "575937654bf757001d8496c9"
  }'

For more information on applying coupons to cart, check out How to apply coupons to a cart in the Coupon Service guide.

Check the reward points balance and history

Customers can view how many points they have left, and see the history of redeemed reward points.

To check the reward points balance and history, the customer sends a request to the Retrieving a reward points summary of a signed-in customer endpoint on the storefront.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -i -X GET 
  https://api.emporix.io/reward-points/public/customer/summary 
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'