Skip to main content

Bonus Points

The bonus points entity is used to manage the client's bonus balance. Each client has only one bonus balance, which changes depending on the client's actions and loyalty program settings.

Bonus points allow for:

  • paying for purchases (according to promotional mechanics settings)
  • acquiring gifts for points

Accrual, deduction, and transfer of bonuses are possible through:

  • promotional mechanics
  • trigger scenarios
  • the client card in the Sailplay interface
  • API requests
Where it is configured

The loyalty program settings page is available in the Sailplay interface: Settings → Loyalty → Bonus Points.

Bonus Accrual​

The base for accrual is the conversion coefficient.

Example: if a purchase is 100 conventional units and the coefficient is 0.01, the client will receive 1 point for the purchase.

Additionally, the coefficient can be changed at the promotion level.

Example: for a client with a special status, the multiplier may be 10, and for every 100 conventional units, the client will receive 10 points instead of 1.

Rounding

Bonuses are accrued as an integer value.
Rounding rules can be set in the settings:

  • for each order position
  • for the entire receipt
Unconfirmed Purchases

If an order is created in the "unconfirmed" status, bonuses can be calculated and displayed, but the client will not be able to use them until the purchase is confirmed.

Bonus Expiration​

A validity period (expiration) can be configured for bonuses if required by business logic.

If a client simultaneously has:

  • points with an expiration date
  • perpetual points

then upon deduction, expiring points will be consumed first (FIFO), and only then — perpetual ones.

Deduction of Points for Discount​

Settings in the Dashboard​

To enable the deduction of bonuses for a discount, configure a promotion with the reward type "Bonus points for discount," in the settings of which the reverse coefficient is set (the cost of 1 bonus point to a conventional currency unit) and the maximum discount size in %, within which it is calculated how many bonus points the client can deduct in a purchase.

Deduction of Bonus Points During Checkout​

Deduction of bonus points must be implemented at the checkout stage.
For this, three fields must be displayed on the page:

  1. Number of bonus points the client has
    The points_confirmed value obtained from the response of the method /api/v2/users/info/ is used.

  2. Number of points available for deduction in the order
    The total_discount_points_max_for_user value returned in the response of the method /api/v2/marketing-actions/calc/light/ is used.
    To obtain this value, a request must be performed with the parameter discount_points_writeoff=0.

  3. Input field for the number of points to be deducted
    The client specifies the number of bonus points they want to deduct within the current order.

Passing Data to the API​

To deduct bonus points in a calculation or purchase creation request, the following parameter must be passed: discount_points_writeoff with the value of the number of points entered by the client.

In this case, the total amount of deducted bonus points is distributed by the Sailplay server automatically:

  • distribution occurs across all products in the order (also, deduction promotions in the Sailplay dashboard can be configured to apply only to specific products);
  • distribution is proportional to the cost of each position relative to the total order amount;
  • all values of deducted bonuses are rounded to integers.

It is also allowed to distribute bonuses for deduction on the partner side. For each position in the promotion calculation method /api/v2/marketing-actions/calc/ or /api/v2/marketing-actions/calc/light/, the discount_points parameter must be passed for each position in the cart array, the maximum value of which will be calculated for each position in the discount_points_max parameter. If deduction is not provided for a certain position or is equal to 0, then you can either add discount_points to this position or pass it with a value of 0.

Example of a cart with passing bonuses for deduction by position: cart={"1":{"sku":"1","price":1000,"quantity":1,"discount_points":500},"2":{"sku":"2","price":555,"quantity":1,"discount_points":0},"3":{"sku":"10001","price":123,"quantity":1}}

Input and Validation Logic​

The client can enter a number of points for deduction not exceeding:

  • their confirmed balance;
  • the deduction limit available for the current order.

Verification of these conditions must be performed on the website or client application side.

Transferring Points Between Clients​

The Sailplay API provides the ability to transfer bonus points between clients. To do this, in a request to the /points/move method, you must specify the identifiers of the clients between whom the transfer will be made, the number of points, and (optionally) the comment text that will be displayed in the client card in the Sailplay dashboard.

Important!

After the transfer, expiring bonuses will become "perpetual"!