multitenetsaas/docs/api/retail/README.md

# Retail Module API Documentation

## Overview

The Retail Module API provides comprehensive functionality for retail management including product catalog, sales processing, inventory management, and customer loyalty programs.

## Products

### Create Product
```http
POST /api/v1/retail/products/
```

**Request Body:**
```json
{
  "sku": "PRD-2024-001",
  "name": "Premium Bluetooth Speaker",
  "description": "High-quality wireless speaker with noise cancellation",
  "category": "electronics",
  "brand": "AudioTech",
  "barcode": "9555123456789",
  "unit": "piece",
  "current_stock": 50,
  "minimum_stock": 10,
  "maximum_stock": 200,
  "purchase_price": 150.00,
  "selling_price": 299.00,
  "tax_rate": 6.0,
  "is_active": true,
  "attributes": {
    "color": ["black", "white", "blue"],
    "warranty_months": 24,
    "weight_kg": 0.8,
    "dimensions_cm": {
      "length": 15,
      "width": 8,
      "height": 8
    }
  }
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "prod_123456",
    "sku": "PRD-2024-001",
    "name": "Premium Bluetooth Speaker",
    "description": "High-quality wireless speaker with noise cancellation",
    "category": "electronics",
    "brand": "AudioTech",
    "barcode": "9555123456789",
    "unit": "piece",
    "current_stock": 50,
    "minimum_stock": 10,
    "maximum_stock": 200,
    "purchase_price": 150.00,
    "selling_price": 299.00,
    "tax_rate": 6.0,
    "is_active": true,
    "attributes": {
      "color": ["black", "white", "blue"],
      "warranty_months": 24,
      "weight_kg": 0.8,
      "dimensions_cm": {
        "length": 15,
        "width": 8,
        "height": 8
      }
    },
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

### Get Product
```http
GET /api/v1/retail/products/{product_id}/
```

### Update Product
```http
PUT /api/v1/retail/products/{product_id}/
```

### List Products
```http
GET /api/v1/retail/products/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `category` - Filter by category
- `brand` - Filter by brand
- `is_active` - Filter by active status
- `search` - Search in name, description, SKU
- `min_price` - Minimum selling price
- `max_price` - Maximum selling price
- `low_stock` - Show only low stock items (true/false)

### Delete Product
```http
DELETE /api/v1/retail/products/{product_id}/
```

### Update Stock
```http
POST /api/v1/retail/products/{product_id}/update-stock/
```

**Request Body:**
```json
{
  "quantity": 25,
  "operation": "add",
  "reason": "New stock received",
  "reference": "PO-2024-001"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "product_id": "prod_123456",
    "previous_stock": 50,
    "quantity_changed": 25,
    "new_stock": 75,
    "operation": "add",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}
```

## Sales

### Create Sale
```http
POST /api/v1/retail/sales/
```

**Request Body:**
```json
{
  "customer_id": "cust_123456",
  "items": [
    {
      "product_id": "prod_123456",
      "quantity": 2,
      "unit_price": 299.00,
      "discount_rate": 10.0
    },
    {
      "product_id": "prod_789012",
      "quantity": 1,
      "unit_price": 150.00
    }
  ],
  "payment_method": "credit_card",
  "payment_details": {
    "card_last_four": "1234",
    "transaction_id": "txn_123456789"
  },
  "notes": "Customer loyalty discount applied"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "sale_123456",
    "customer_id": "cust_123456",
    "items": [
      {
        "product_id": "prod_123456",
        "quantity": 2,
        "unit_price": 299.00,
        "discount_rate": 10.0,
        "tax_rate": 6.0,
        "subtotal": 538.20,
        "tax_amount": 32.29,
        "total": 570.49
      }
    ],
    "payment_method": "credit_card",
    "payment_status": "completed",
    "subtotal": 748.00,
    "discount_amount": 59.80,
    "tax_amount": 44.88,
    "total": 733.08,
    "status": "completed",
    "created_at": "2024-01-01T00:00:00Z"
  }
}
```

### Get Sale
```http
GET /api/v1/retail/sales/{sale_id}/
```

### List Sales
```http
GET /api/v1/retail/sales/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `customer_id` - Filter by customer
- `status` - Filter by status (pending, completed, cancelled, refunded)
- `payment_method` - Filter by payment method
- `date_from` - Filter by date (YYYY-MM-DD)
- `date_to` - Filter by date (YYYY-MM-DD)

### Update Sale Status
```http
PUT /api/v1/retail/sales/{sale_id}/status/
```

**Request Body:**
```json
{
  "status": "refunded",
  "reason": "Customer return"
}
```

### Refund Sale
```http
POST /api/v1/retail/sales/{sale_id}/refund/
```

**Request Body:**
```json
{
  "items": [
    {
      "product_id": "prod_123456",
      "quantity": 1,
      "reason": "Defective product"
    }
  ],
  "refund_method": "credit_card",
  "notes": "Partial refund for defective item"
}
```

## Customers

### Create Customer
```http
POST /api/v1/retail/customers/
```

**Request Body:**
```json
{
  "first_name": "Ahmad",
  "last_name": "Ibrahim",
  "email": "ahmad.ibrahim@example.com",
  "phone_number": "+60123456789",
  "ic_number": "900101-01-1234",
  "address": {
    "street": "123 Customer Street",
    "city": "Kuala Lumpur",
    "state": "Wilayah Persekutuan",
    "postal_code": "50050",
    "country": "Malaysia"
  },
  "loyalty_tier": "bronze",
  "loyalty_points": 0,
  "notes": "VIP customer"
}
```

### Get Customer
```http
GET /api/v1/retail/customers/{customer_id}/
```

### Update Customer
```http
PUT /api/v1/retail/customers/{customer_id}/
```

### List Customers
```http
GET /api/v1/retail/customers/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `loyalty_tier` - Filter by loyalty tier (bronze, silver, gold, platinum)
- `search` - Search in name, email, phone
- `is_active` - Filter by active status

### Delete Customer
```http
DELETE /api/v1/retail/customers/{customer_id}/
```

### Get Customer Purchase History
```http
GET /api/v1/retail/customers/{customer_id}/purchase-history/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `date_from` - Filter by date (YYYY-MM-DD)
- `date_to` - Filter by date (YYYY-MM-DD)

## Inventory Management

### Stock Adjustment
```http
POST /api/v1/retail/inventory/adjust/
```

**Request Body:**
```json
{
  "product_id": "prod_123456",
  "quantity": -5,
  "reason": "Damaged items",
  "reference": "ADJ-2024-001",
  "notes": "5 items damaged during delivery"
}
```

### Stock Transfer
```http
POST /api/v1/retail/inventory/transfer/
```

**Request Body:**
```json
{
  "product_id": "prod_123456",
  "quantity": 10,
  "from_location": "Warehouse A",
  "to_location": "Store B",
  "reference": "TRANSFER-2024-001",
  "notes": "Transfer for weekend promotion"
}
```

### Stock Alert
```http
GET /api/v1/retail/inventory/alerts/
```

**Query Parameters:**
- `type` - Alert type (low_stock, overstock, expiry)
- `severity` - Severity level (low, medium, high)

### Inventory Report
```http
GET /api/v1/retail/inventory/report/
```

**Query Parameters:**
- `category` - Filter by category
- `date_from` - Filter by date (YYYY-MM-DD)
- `date_to` - Filter by date (YYYY-MM-DD)
- `format` - Output format (json, csv)

## Loyalty Program

### Update Loyalty Points
```http
POST /api/v1/retail/loyalty/update-points/
```

**Request Body:**
```json
{
  "customer_id": "cust_123456",
  "points": 50,
  "operation": "add",
  "reason": "Purchase reward",
  "reference": "sale_123456"
}
```

### Get Loyalty Tiers
```http
GET /api/v1/retail/loyalty/tiers/
```

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "name": "Bronze",
      "min_points": 0,
      "max_points": 999,
      "discount_rate": 0.0,
      "benefits": ["Basic membership"]
    },
    {
      "name": "Silver",
      "min_points": 1000,
      "max_points": 4999,
      "discount_rate": 5.0,
      "benefits": ["5% discount", "Birthday voucher"]
    },
    {
      "name": "Gold",
      "min_points": 5000,
      "max_points": 9999,
      "discount_rate": 10.0,
      "benefits": ["10% discount", "Priority support", "Free shipping"]
    },
    {
      "name": "Platinum",
      "min_points": 10000,
      "max_points": null,
      "discount_rate": 15.0,
      "benefits": ["15% discount", "VIP support", "Exclusive events"]
    }
  ]
}
```

### Redeem Loyalty Points
```http
POST /api/v1/retail/loyalty/redeem/
```

**Request Body:**
```json
{
  "customer_id": "cust_123456",
  "points": 100,
  "reward_type": "discount",
  "reference": "sale_123456"
}
```

## Reports and Analytics

### Sales Report
```http
GET /api/v1/retail/reports/sales/
```

**Query Parameters:**
- `date_from` - Filter by date (YYYY-MM-DD)
- `date_to` - Filter by date (YYYY-MM-DD)
- `group_by` - Group by (day, week, month, category, product)
- `format` - Output format (json, csv, pdf)

### Inventory Report
```http
GET /api/v1/retail/reports/inventory/
```

**Query Parameters:**
- `category` - Filter by category
- `location` - Filter by location
- `format` - Output format (json, csv, pdf)

### Customer Analytics
```http
GET /api/v1/retail/reports/customers/
```

**Query Parameters:**
- `date_from` - Filter by date (YYYY-MM-DD)
- `date_to` - Filter by date (YYYY-MM-DD)
- `segment_by` - Segment by (loyalty_tier, location, purchase_frequency)
- `format` - Output format (json, csv, pdf)

## Malaysian Features

### SST Calculation
All price-related endpoints include automatic SST calculation:
```json
{
  "subtotal": 299.00,
  "sst_rate": 0.06,
  "sst_amount": 17.94,
  "total": 316.94
}
```

### Malaysian Currency
All amounts are in Malaysian Ringgit (MYR).

### Malaysian Address Format
Customer addresses follow Malaysian address format with states and postal codes.

### Halal Certification Support
Products can include halal certification information:
```json
{
  "attributes": {
    "halal_certified": true,
    "halal_certification_number": "JAKIM-1234-5678",
    "halal_expiry_date": "2025-12-31"
  }
}
```