multitenetsaas/docs/api/retail

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

POST /api/v1/retail/products/

Request Body:

{
  "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:

{
  "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

GET /api/v1/retail/products/{product_id}/

Update Product

PUT /api/v1/retail/products/{product_id}/

List Products

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

DELETE /api/v1/retail/products/{product_id}/

Update Stock

POST /api/v1/retail/products/{product_id}/update-stock/

Request Body:

{
  "quantity": 25,
  "operation": "add",
  "reason": "New stock received",
  "reference": "PO-2024-001"
}

Response:

{
  "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

POST /api/v1/retail/sales/

Request Body:

{
  "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:

{
  "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

GET /api/v1/retail/sales/{sale_id}/

List Sales

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

PUT /api/v1/retail/sales/{sale_id}/status/

Request Body:

{
  "status": "refunded",
  "reason": "Customer return"
}

Refund Sale

POST /api/v1/retail/sales/{sale_id}/refund/

Request Body:

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

Customers

Create Customer

POST /api/v1/retail/customers/

Request Body:

{
  "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

GET /api/v1/retail/customers/{customer_id}/

Update Customer

PUT /api/v1/retail/customers/{customer_id}/

List Customers

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

DELETE /api/v1/retail/customers/{customer_id}/

Get Customer Purchase History

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

POST /api/v1/retail/inventory/adjust/

Request Body:

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

Stock Transfer

POST /api/v1/retail/inventory/transfer/

Request Body:

{
  "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

GET /api/v1/retail/inventory/alerts/

Query Parameters:

• type - Alert type (low_stock, overstock, expiry)
• severity - Severity level (low, medium, high)

Inventory Report

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

POST /api/v1/retail/loyalty/update-points/

Request Body:

{
  "customer_id": "cust_123456",
  "points": 50,
  "operation": "add",
  "reason": "Purchase reward",
  "reference": "sale_123456"
}

Get Loyalty Tiers

GET /api/v1/retail/loyalty/tiers/

Response:

{
  "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

POST /api/v1/retail/loyalty/redeem/

Request Body:

{
  "customer_id": "cust_123456",
  "points": 100,
  "reward_type": "discount",
  "reference": "sale_123456"
}

Reports and Analytics

Sales Report

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

GET /api/v1/retail/reports/inventory/

Query Parameters:

• category - Filter by category
• location - Filter by location
• format - Output format (json, csv, pdf)

Customer Analytics

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:

{
  "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:

{
  "attributes": {
    "halal_certified": true,
    "halal_certification_number": "JAKIM-1234-5678",
    "halal_expiry_date": "2025-12-31"
  }
}