From 4c4b9df032e7becb3d1fbe9858ffef55e3024ec3 Mon Sep 17 00:00:00 2001 From: Aleksandr Zavadkin Date: Mon, 7 Jul 2025 15:29:44 +0300 Subject: [PATCH] docs(includes): loyalty methods specifics Signed-off-by: Aleksandr Zavadkin --- source/includes/_loyalty.apply.md.erb | 2 +- source/includes/_loyalty.cancel.md.erb | 4 ++++ source/includes/_loyalty.change.md.erb | 4 ++++ source/includes/_loyalty.estimate.md.erb | 5 +++++ source/includes/_loyalty.event_bonus.md.erb | 4 ++++ source/includes/_loyalty.event_bonus_history.md.erb | 4 ++++ source/includes/_loyalty.join.md.erb | 6 ++++++ source/includes/_loyalty.quit.md.erb | 6 ++++++ source/includes/_loyalty.status.md.erb | 5 +++++ 9 files changed, 39 insertions(+), 1 deletion(-) diff --git a/source/includes/_loyalty.apply.md.erb b/source/includes/_loyalty.apply.md.erb index cb1fed72..242895de 100644 --- a/source/includes/_loyalty.apply.md.erb +++ b/source/includes/_loyalty.apply.md.erb @@ -95,7 +95,7 @@ curl --header "Content-Type: application/json" \ `POST https://<%= config[:api_endpoint] %>/loyalty/checkout/apply` -When clients proceed to the payment step, execute the this method to charge for bonuses and get the final payment value. +When clients proceed to the payment step, execute the method to charge for bonuses and get the final payment value. If `charge_bonuses` parameter is missing or `false`, only offers and discounts will be applied. Bonuses will not be calculated in the final order value and charged. diff --git a/source/includes/_loyalty.cancel.md.erb b/source/includes/_loyalty.cancel.md.erb index 331efce3..74e44631 100644 --- a/source/includes/_loyalty.cancel.md.erb +++ b/source/includes/_loyalty.cancel.md.erb @@ -66,3 +66,7 @@ If client failed to pay for order and don't plan to proceed, you have to cancel Just send the same payload to `loyalty/checkout/cancel` to refund bonuses. +Specifics: + +1. Cancels a specific event bonus if it has the cancellable flag +2. Only works with bonuses created via event_bonus diff --git a/source/includes/_loyalty.change.md.erb b/source/includes/_loyalty.change.md.erb index 5d62ca83..d20adb28 100644 --- a/source/includes/_loyalty.change.md.erb +++ b/source/includes/_loyalty.change.md.erb @@ -97,4 +97,8 @@ When client partially returns some products from an order, it's needed to recalc Send an updated list of client's cart to refund bonuses and calculate how much money to refund. +Specifics: +1. Recalculates the order in case of product returns or replacements +2. Adjusts money and bonuses, including possible refunds +3. Returns the delta (negative for refund, positive for extra payment) diff --git a/source/includes/_loyalty.estimate.md.erb b/source/includes/_loyalty.estimate.md.erb index 1a23b539..3db0a8a4 100644 --- a/source/includes/_loyalty.estimate.md.erb +++ b/source/includes/_loyalty.estimate.md.erb @@ -103,3 +103,8 @@ If `charge_bonuses` is missing or `false`, only offers and discounts will be app When clients proceed to the payment step, execute the next method `apply` to charge for bonuses and get the final payment value. +Specifics: + +1. This is a safe, read-only method that simulates order calculation — no bonuses are deducted +2. You can safely call this method multiple times for the same cart + diff --git a/source/includes/_loyalty.event_bonus.md.erb b/source/includes/_loyalty.event_bonus.md.erb index df87bedf..7e1ead7a 100644 --- a/source/includes/_loyalty.event_bonus.md.erb +++ b/source/includes/_loyalty.event_bonus.md.erb @@ -19,6 +19,10 @@ curl 'https://<%= config[:api_endpoint] %>/loyalty/basic/event_bonus' \ Method increase bonuses. This method is used to increase user bonuses that aren't related to an order. It can be any action, for example, registration in the mobile applications. Bonuses added by this method have activated status and can be used immediately. +Specifics: + +1. Bonuses are immediately confirmed and available. + ### HTTP Request `POST https://<%= config[:api_endpoint] %>/loyalty/basic/event_bonus` diff --git a/source/includes/_loyalty.event_bonus_history.md.erb b/source/includes/_loyalty.event_bonus_history.md.erb index ab461c7f..d772fd31 100644 --- a/source/includes/_loyalty.event_bonus_history.md.erb +++ b/source/includes/_loyalty.event_bonus_history.md.erb @@ -37,6 +37,10 @@ curl 'https://<%= config[:api_endpoint] %>/loyalty/bonuses/event_bonus_history?s Method return member's bonuses history which were created with `loyalty/basic/event_bonus` method only. This allows to cancel some bonuses by ID using `loyalty/bonuses/cancel` method. +Specifics: + +1. Indicates which bonuses can be canceled via the cancel method (cancellable: true) + ### HTTP Request `GET https://<%= config[:api_endpoint] %>/loyalty/bonuses/event_bonus_history` diff --git a/source/includes/_loyalty.join.md.erb b/source/includes/_loyalty.join.md.erb index 4399d523..3adcc3e9 100644 --- a/source/includes/_loyalty.join.md.erb +++ b/source/includes/_loyalty.join.md.erb @@ -68,6 +68,12 @@ curl --header "Content-Type: application/json" \ Method to register a user as a member of loyalty program. Server-to-server integration method only. +Specifics: + +1. The user is registered even if the loyalty program is currently inactive +2. If the user is already a member, the method still returns "success": true and doesn't change their data +3. At least the phone field is required; email is optional but should be passed if available + ### Query Parameters | Parameter | Required | Description | diff --git a/source/includes/_loyalty.quit.md.erb b/source/includes/_loyalty.quit.md.erb index e6a7303a..17dcb24e 100644 --- a/source/includes/_loyalty.quit.md.erb +++ b/source/includes/_loyalty.quit.md.erb @@ -60,6 +60,12 @@ curl --header "Content-Type: application/json" \ Method deletes loyalty member profile from database by identifier (phone number). Loyalty level and bonuses will not be deleted immediately to prevent accident data loss, but member won't be able to receive membership benefits on next purchases. +Specifics: + +1. After this method is called, the user is no longer considered a loyalty member +2. Bonuses and loyalty level are preserved internally for safety but become inactive and inaccessible for use + + ### Query Parameters | Parameter | Required | Description | diff --git a/source/includes/_loyalty.status.md.erb b/source/includes/_loyalty.status.md.erb index 785e4f9b..d884a69f 100644 --- a/source/includes/_loyalty.status.md.erb +++ b/source/includes/_loyalty.status.md.erb @@ -81,6 +81,11 @@ curl https://<%= config[:api_endpoint] %>/loyalty/members/status?shop_id=...&sho Returns the member's status in the loyalty program: member or not, current level and level expiration date. +Specifics: + +1. The method only accepts the identifier as a phone number (email is not supported) +2. If the user is not a member, the response is still "success": true with "member": false + ### Query Parameters | Parameter | Required | Description |