diff --git a/source/includes/_loyalty.balance.md.erb b/source/includes/_loyalty.balance.md.erb index ab3dd02..5849755 100644 --- a/source/includes/_loyalty.balance.md.erb +++ b/source/includes/_loyalty.balance.md.erb @@ -8,11 +8,32 @@ curl 'https://<%= config[:api_endpoint] %>/loyalty/bonuses/balance?shop_id=SHOP_ > The above command returns JSON structured like this: ```json +/* + * API Response Structure: + * + * Root Level: + * status: string - "success" or "error" + * payload: object - Main data container + * + * Balance Object: + * active: integer - Available bonus points + * pending: integer - Pending activation points + * expiring: integer - Soon-to-expire points + * expire_in: string - Expiration date (YYYY-MM-DD) + * expiring_transactions: array - List of expiring bonus transactions + */ + { - "active": 123, - "pending": 456, - "expiring": 789, - "expire_in": "2030-12-12" + "status": "success", + "payload": { + "balance": { + "active": 276, + "pending": 0, + "expiring": 0, + "expire_in": "2025-07-18", + "expiring_transactions": [] + } + } } ``` diff --git a/source/includes/_loyalty.details.md.erb b/source/includes/_loyalty.details.md.erb index 814c516..e862958 100644 --- a/source/includes/_loyalty.details.md.erb +++ b/source/includes/_loyalty.details.md.erb @@ -44,41 +44,94 @@ curl --header "Content-Type: application/json" \ > The above command returns JSON structured like this: ```json + +/* + * API Response Structure Documentation (with Type Annotations): + * + * Root Object: + * status: string - Operation status ("success" or "error") + * payload: object - Contains all order data + * + * Order Summary: + * order_id: string - Unique order identifier (format: alphanumeric) + * identifier: string - Customer loyalty ID (format: phone/email) + * payment_type: string|null - Payment method identifier or null + * products_total: float - Total item count (decimal supported) + * + * Financial Summary: + * order_total: float - Grand total before discounts (2 decimal places) + * saved_total: float - Total savings (discounts + bonuses) + * saved_by_discounts: float - Savings from discount offers + * saved_by_bonuses: float - Savings from loyalty points + * order_to_pay: float - Final amount due (order_total - saved_total) + * + * Loyalty Points: + * order_bonuses_to_charge: float - Points redeemed + * bonuses_balance: integer - Remaining points balance + * bonuses_reward: integer - Points to be awarded + * bonuses_referrer_reward: integer - Points awarded to referrer + * + * Item Object: + * uniqid: string - Unique product ID + * quantity: float - Item count (supports decimal quantities) + * price: float - Unit price (2 decimal places) + * total: float - Line item total (price × quantity) + * + * Item Flags (all boolean): + * discountable - Eligible for discounts + * bonusable - Eligible for points redemption + * rewardable - Eligible for points earning + * + * Applied Discounts (all float): + * paid_with_offers - Special offers amount + * paid_with_discounts - Regular discounts amount + * paid_with_referral_discounts - Referral program discounts + * paid_with_bonuses - Amount covered by loyalty points + * + * Purchase Limits (all float): + * max_discountable_amount - Maximum allowable discount + * max_payable_by_bonuses - Maximum payable with points + * + * Final Calculations (all float): + * total_after_discounts - Final line item amount + * total_after_discounts_per_product - Final unit price + */ + { - "success": true, + "status": "success", "payload": { - "order_id": "...", // (string) Order ID - "identifier": "...", // (string) Loyalty member identifier - "payment_type": "...", // (string) Payment type - "products_total": ..., // (integer) Total products in the cart - "order_total": ..., // (decimal) Order total value (initial) - "saved_total": ..., // (decimal) Money saved total (discounts and bonuses) - "saved_by_discounts": ..., // (decimal) Money saved by discounts and offers - "saved_by_bonuses": ..., // (decimal) Money saved by bonuses - "order_to_pay": ..., // (decimal) Order total to pay after discounts - "order_bonuses_to_charge": ..., // (integer) Total bonuses used in this order - "bonuses_reward": ..., // (integer) Bonuses amount to be rewarded after the purchase + "order_id": "ORDER ID", + "identifier": "PHONE NUMBER", + "payment_type": null, + "products_total": 5.0, + "order_total": 6000.0, + "saved_total": 498.0, + "saved_by_discounts": 0, + "saved_by_bonuses": 498.0, + "order_to_pay": 5502.0, + "order_bonuses_to_charge": 498.0, + "bonuses_balance": 500, + "bonuses_reward": 274, + "bonuses_referrer_reward": 0, "items": [ { - "uniqid": "...", // (string) Item ID - "quantity": ..., // (integer) Quantity - "price": ..., // (decimal) Initial product price - "total": ..., // (decimal) Total value of a position (price * quantity) - "discountable": ..., //(bool) Allowed for discounts - "bonusable": ..., // (bool) Allowed for bonuses - "rewardable": ..., // (bool) Allowed to be rewarded with bonuses - "paid_with_offers": ..., // (decimal) Paid with offers - "paid_with_offers_per_product": ..., // (decimal) Paid with offers per 1 item - "paid_with_discounts": ..., // (decimal) Paid with discounts - "paid_with_discounts_per_product": ..., // (decimal) Paid with discounts - "paid_with_bonuses": ..., // (decimal) Paid with bonuses - "paid_with_bonuses_per_product": ..., // (decimal) Paid with bonuses - "bonuses_used": ..., // (integer) Bonuses used for this position - "bonuses_used_per_product": ..., // (integer) Bonuses used per 1 pcs of this product - "total_after_discounts": ... // (decimal) To paid with money after all discounts - }, - ... - ], + "uniqid": "17520", + "quantity": 4.0, + "price": 1000.0, + "total": 4000.0, + "discountable": true, + "bonusable": true, + "rewardable": true, + "paid_with_offers": 0, + "paid_with_discounts": 0, + "paid_with_referral_discounts": 0, + "paid_with_bonuses": 332.0, + "max_discountable_amount": 3600.0, + "max_payable_by_bonuses": 400.0, + "total_after_discounts": 3668.0, + "total_after_discounts_per_product": 917.0 + } + ] } } ``` diff --git a/source/includes/_loyalty.orders-history.md.erb b/source/includes/_loyalty.orders-history.md.erb index 07c14d8..bdf396f 100644 --- a/source/includes/_loyalty.orders-history.md.erb +++ b/source/includes/_loyalty.orders-history.md.erb @@ -44,25 +44,51 @@ curl --header "Content-Type: application/json" \ > The above command returns JSON structured like this: ```json +/* + * API Response Example: + * + * Root Level: + * status: string - Operation status ("success" or "error") + * payload: object - Contains orders data + * + * Orders Array: + * orders[].id: string - Unique order ID (alphanumeric) + * orders[].date: string - Order date in YYYY-MM-DD format + * orders[].status: string - Current status ("confirmed", "completed", etc.) + * orders[].total: float - Final paid amount (2 decimal places) + * + * Items Array: + * items[].id: string - Product ID (numeric string) + * items[].name: string - Full product name with brand + * items[].quantity: float - Item count (supports .0 decimals) + * items[].price: float - Unit price after discounts + */ + { - "success": true, + "status": "success", "payload": { "orders": [ { - "id": "...", // Order ID - "date": "...", // Order date YYYY-MM-DD - "status": "...", // Order status - "total": ..., // Paid amount + "id": "order66", + "date": "2025-06-09", + "status": "confirmed", + "total": 5502.0, "items": [ { - "id": "...", // Product ID - "name": "...", // Product name - "quantity": ..., // Quantity (integer) - "price": ... // Price per product after all discounts, offers and bonuses - }, ... + "id": "17520", + "name": "Smartphone Lenovo P70", + "quantity": 4.0, + "price": 917.0 + }, + { + "id": "17515", + "name": "Smartphone Nokia 2 Dual Sim", + "quantity": 1.0, + "price": 1834.0 + } ] - }, ... - ], + } + ] } } ```