# Customer Discount APIs This document describes the customer-facing discount APIs that allow customers to view running discounts and their details. ## API Endpoints ### 1. Get Running Discounts (Authenticated) **Endpoint:** `GET /api/customer/discounts` **Authentication:** Required (Customer token) **Description:** Returns all active discounts that are applicable to the authenticated customer. **Headers:** ``` Authorization: Bearer {customer_token} ``` **Response:** ```json { "status": true, "message": "Running discounts retrieved successfully", "data": [ { "id": 1, "name": "Summer Sale 20% Off", "code": null, "logo": null, "discount_type": "productAdjustment", "discount_value": 10, "discount_method": "percentageDiscount", "min_buy_qty": 1, "max_buy_qty": null, "use_limit": 100, "priority": 3, "apply_date": "2024-03-19T18:30:00.000000Z", "end_date": "2026-04-19T18:30:00.000000Z", "is_primary": true, "filter_summary": "Categories: CBD Products, Wellness", "applicability": "Categories: CBD Products, Wellness" }, { "id": 3, "name": "Buy 4 Get 1 Free", "code": null, "logo": null, "discount_type": "buyXgetY", "discount_value": 0, "discount_method": "free", "min_buy_qty": 4, "max_buy_qty": null, "use_limit": null, "priority": 1, "apply_date": "2023-12-31T18:30:00.000000Z", "end_date": "2026-12-30T18:30:00.000000Z", "is_primary": true, "filter_summary": "Products: WOODSTOCK WILDWOOD CBD LIVE RESIN 2GM DISPO 5CT/ BOX", "applicability": "Products: WOODSTOCK WILDWOOD CBD LIVE RESIN 2GM DISPO 5CT/ BOX", "buy_x_get_y_details": { "buy_quantity": 4, "is_recursive": true, "free_products": [ { "product_id": 314, "variation_id": 907, "quantity": 1 } ] } } ], "total_count": 2 } ``` ### 2. Get Single Discount Details (Authenticated) **Endpoint:** `GET /api/customer/discounts/{id}` **Authentication:** Required (Customer token) **Description:** Returns detailed information about a specific discount including filter criteria. **Headers:** ``` Authorization: Bearer {customer_token} ``` **Response:** ```json { "status": true, "message": "Discount details retrieved successfully", "data": { "id": 1, "name": "Summer Sale 20% Off", "code": null, "logo": null, "discount_type": "productAdjustment", "discount_value": 10, "discount_method": "percentageDiscount", "min_buy_qty": 1, "max_buy_qty": null, "use_limit": 100, "priority": 3, "apply_date": "2024-03-19T18:30:00.000000Z", "end_date": "2026-04-19T18:30:00.000000Z", "is_primary": true, "filter_summary": "Categories: CBD Products, Wellness", "applicability": "Categories: CBD Products, Wellness", "filter_details": { "categories": { "operation": "in", "description": "Included categories", "items": [ { "id": 35, "name": "CBD Products", "description": "Cannabidiol products" }, { "id": 36, "name": "Wellness", "description": "Health and wellness products" } ] } } } } ``` ### 3. Get Public Discounts (No Authentication) **Endpoint:** `GET /api/discounts` **Authentication:** Not required **Description:** Returns all active discounts for promotional purposes. This endpoint can be used to display discounts on public pages. **Response:** ```json { "status": true, "message": "Running discounts retrieved successfully", "data": [ { "id": 1, "name": "Summer Sale 20% Off", "code": null, "logo": null, "discount_type": "productAdjustment", "discount_value": 10, "discount_method": "percentageDiscount", "min_buy_qty": 1, "max_buy_qty": null, "use_limit": 100, "priority": 3, "apply_date": "2024-03-19T18:30:00.000000Z", "end_date": "2026-04-19T18:30:00.000000Z", "is_primary": true, "filter_summary": "Categories: CBD Products, Wellness", "applicability": "Categories: CBD Products, Wellness" } ], "total_count": 1 } ``` ## Response Fields Explanation ### Common Fields - `id`: Unique discount identifier - `name`: Discount name/title - `code`: Coupon code (if applicable) - `logo`: Discount logo image URL - `discount_type`: Type of discount (productAdjustment, cartAdjustment, freeShipping, buyXgetY) - `discount_value`: Discount value (percentage, fixed amount, etc.) - `discount_method`: Method of discount calculation (percentageDiscount, fixedDiscount, free) - `min_buy_qty`: Minimum quantity required to qualify - `max_buy_qty`: Maximum quantity limit - `use_limit`: Usage limit for the discount - `priority`: Priority level (higher number = higher priority) - `apply_date`: Start date of the discount - `end_date`: End date of the discount - `is_primary`: Whether this is a primary discount - `filter_summary`: Human-readable summary of what the discount applies to - `applicability`: Detailed applicability description ### Discount Type Specific Fields #### buyXgetY Discounts - `buy_x_get_y_details`: Contains buy quantity, recursive flag, and free products list #### cartAdjustment Discounts - `cart_rules`: Contains minimum order value and maximum discount amount #### freeShipping Discounts - `shipping_rules`: Contains minimum order value and maximum discount amount ### Filter Details (Single Discount Endpoint) - `filter_details`: Detailed breakdown of filter criteria including: - `categories`: Category-based filters with operation and items - `brands`: Brand-based filters with operation and items - `products`: Product-based filters with operation and items - `variations`: Variation-based filters with operation and count ## Error Responses ### Authentication Error (401) ```json { "status": false, "message": "Customer not authenticated" } ``` ### Not Found Error (404) ```json { "status": false, "message": "Discount not found or not active" } ``` ### Not Applicable Error (403) ```json { "status": false, "message": "Discount not applicable for this customer" } ``` ### Server Error (500) ```json { "status": false, "message": "Failed to retrieve discounts", "error": "Error details" } ``` ## Usage Examples ### JavaScript/Fetch Example ```javascript // Get running discounts for authenticated customer const response = await fetch('/api/customer/discounts', { headers: { 'Authorization': 'Bearer ' + customerToken, 'Content-Type': 'application/json' } }); const data = await response.json(); console.log(data.data); // Array of discounts // Get specific discount details const discountResponse = await fetch('/api/customer/discounts/1', { headers: { 'Authorization': 'Bearer ' + customerToken, 'Content-Type': 'application/json' } }); const discountData = await discountResponse.json(); console.log(discountData.data); // Single discount details // Get public discounts (no authentication) const publicResponse = await fetch('/api/discounts'); const publicData = await publicResponse.json(); console.log(publicData.data); // Array of public discounts ``` ### cURL Examples ```bash # Get running discounts (authenticated) curl -X GET "http://your-domain.com/api/customer/discounts" \ -H "Authorization: Bearer YOUR_CUSTOMER_TOKEN" # Get specific discount details curl -X GET "http://your-domain.com/api/customer/discounts/1" \ -H "Authorization: Bearer YOUR_CUSTOMER_TOKEN" # Get public discounts curl -X GET "http://your-domain.com/api/discounts" ``` ## Notes 1. **Priority System**: Discounts are ordered by priority (higher number = higher priority). Only one discount type applies per product based on priority. 2. **Filter Criteria**: The APIs provide both summary and detailed filter information to help customers understand what products qualify for each discount. 3. **Customer Context**: Authenticated endpoints consider customer-specific rules and eligibility. 4. **Public Access**: The public endpoint can be used for promotional displays without requiring customer authentication.