# Nearle LiveSetup Write APIs (POST, PUT, DELETE) Directory

This document details the **POST, PUT, and DELETE** endpoints under the `LiveSetup` routing namespace `/live/api/...`, providing exact structures for all required JSON request bodies.

* **Base URL**: `https://jupiter.nearle.app/`
* **Format**: HTTP Header `Content-Type: application/json` is required for all payloads.

---

## Table of Contents
1. [👤 Users & Authorization APIs](#1-users--authorization-apis)
2. [👥 Customer Management APIs](#2-customer-management-apis)
3. [🏢 Tenant & Location APIs](#3-tenant--location-apis)
4. [📦 Products & Catalog APIs](#4-products--catalog-apis)
5. [🛒 Order Management APIs](#5-order-management-apis)
6. [🚚 Deliveries & Dispatch APIs](#6-deliveries--dispatch-apis)
7. [🤝 Partner & Rider Operations APIs](#7-partner--rider-operations-apis)
8. [🧾 Invoices & Billing APIs](#8-invoices--billing-apis)
9. [🛠️ Utilities & Webhooks APIs](#9-utilities--webhooks-apis)
10. [💳 Payments APIs](#10-payments-apis)

---

## 1. 👤 Users & Authorization APIs

### 1.1 User Login (Generic / Staff / Admin)
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/users/login`
* **Request Body**:
  ```json
  {
    "username": "admin_nearle",
    "password": "secure_password_hash"
  }
  ```

### 1.2 Tenant Login
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/users/tenant/login`
* **Request Body**:
  ```json
  {
    "username": "tenant_manager",
    "password": "secure_password_hash"
  }
  ```

### 1.3 Partner Login
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/users/partner/login`
* **Request Body**:
  ```json
  {
    "username": "logistics_partner_ceo",
    "password": "secure_password_hash"
  }
  ```

### 1.4 Rider Authentication (V1)
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/users/rider/login`
* **Request Body**:
  ```json
  {
    "username": "rider_john",
    "password": "rider_password"
  }
  ```

### 1.5 Rider Authentication with PIN & FCM Token (V2)
* **URL**: `POST https://jupiter.nearle.app/live/api/v2/users/rider/login`
* **Request Body**:
  ```json
  {
    "username": "rider_john",
    "pin": 1234,
    "userfcmtoken": "fcm_device_token_abc123",
    "deviceid": "device_uuid_981249",
    "devicetype": "android"
  }
  ```

### 1.6 Tenant Web Login
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/users/tenant/weblogin`
* **Request Body**:
  ```json
  {
    "username": "tenant_web_admin",
    "password": "secure_password_hash"
  }
  ```

### 1.7 Create App User (V1 / V2)
* **URLs**: 
  * `POST https://jupiter.nearle.app/live/api/v1/users/create`
  * `POST https://jupiter.nearle.app/live/api/v2/users/create`
* **Request Body**:
  ```json
  {
    "userid": 0,
    "authname": "rider_joe",
    "firstname": "Joe",
    "lastname": "Smith",
    "password": "joe_password_raw",
    "email": "joe.smith@nearle.app",
    "contactno": "+61400111222",
    "roleid": 4,
    "pin": 1234,
    "tenantid": 8,
    "locationid": 45,
    "applocationid": 5,
    "status": "Active"
  }
  ```

### 1.8 Update App User Details (V1 / V2)
* **URLs**:
  * `PUT https://jupiter.nearle.app/live/api/v1/users/update`
  * `PUT https://jupiter.nearle.app/live/api/v2/users/update`
* **Request Body**:
  ```json
  {
    "userid": 12,
    "authname": "rider_joe",
    "firstname": "Joseph",
    "lastname": "Smith",
    "email": "joseph.smith@nearle.app",
    "contactno": "+61400111222",
    "roleid": 4,
    "pin": 1234,
    "tenantid": 8,
    "locationid": 45,
    "applocationid": 5,
    "status": "Active"
  }
  ```

### 1.9 Delete App User
* **URL**: `DELETE https://jupiter.nearle.app/live/api/v1/users/delete`
* **Request Body**:
  ```json
  {
    "userid": 12
  }
  ```

---

## 2. 👥 Customer Management APIs

### 2.1 Customer Login (Mobile OTP or Contact verification)
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/customers/login`
* **Request Body**:
  ```json
  {
    "contactno": "+61411222333"
  }
  ```

### 2.2 Register Customer
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/customers/create`
* **Request Body**:
  ```json
  {
    "customerid": 0,
    "tenantid": 8,
    "applocationid": 5,
    "firstname": "Jane",
    "lastname": "Doe",
    "email": "jane.doe@example.com",
    "contactno": "+61411222333",
    "dob": "1992-06-15",
    "gender": "Female",
    "status": "Active"
  }
  ```

### 2.3 Update Customer Profile
* **URL**: `PUT https://jupiter.nearle.app/live/api/v1/customers/update`
* **Request Body**:
  ```json
  {
    "customerid": 4082,
    "tenantid": 8,
    "applocationid": 5,
    "firstname": "Jane",
    "lastname": "Smith",
    "email": "jane.smith@example.com",
    "contactno": "+61411222333",
    "dob": "1992-06-15",
    "gender": "Female",
    "status": "Active"
  }
  ```

### 2.4 Create Customer Address Locations
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/customers/createlocations`
* **Request Body**:
  ```json
  [
    {
      "locationid": 0,
      "customerid": 4082,
      "locationname": "Home Address",
      "address": "100 Berry St, North Sydney NSW 2060",
      "suburb": "North Sydney",
      "city": "Sydney",
      "state": "NSW",
      "postcode": "2060",
      "latitude": "-33.8398",
      "longitude": "151.2058",
      "status": "Active"
    }
  ]
  ```

### 2.5 Delete Customer Profile
* **URL**: `DELETE https://jupiter.nearle.app/live/api/v1/customers/delete`
* **Request Body**:
  ```json
  {
    "customerid": 4082
  }
  ```

### 2.6 Submit Customer Support Request
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/customers/createcustomerrequest`
* **Request Body**:
  ```json
  {
    "customerid": 4082,
    "subject": "Missing items in order ORD-000843",
    "description": "Apples were missing from my fresh produce bag.",
    "category": "Refund/Missing Items"
  }
  ```

---

## 3. 🏢 Tenant & Location APIs

### 3.1 Create Tenant
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/tenants/create`
* **Request Body**:
  ```json
  {
    "tenantid": 0,
    "tenantname": "Sydney Fresh Grocers",
    "status": "Active"
  }
  ```

### 3.2 Create Tenant Location / Branch
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/tenants/createlocation`
* **Request Body**:
  ```json
  {
    "tenantid": 8,
    "locationname": "North Sydney Outlet",
    "address": "45 Berry St",
    "suburb": "North Sydney",
    "city": "Sydney",
    "state": "NSW",
    "postcode": "2060",
    "latitude": "-33.8398",
    "longitude": "151.2058",
    "status": "Active"
  }
  ```

### 3.3 Create Tenant User Setup
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/tenants/createtenantuser`
* **Request Body**:
  ```json
  {
    "tenantid": 8,
    "userid": 12,
    "status": "Active"
  }
  ```

### 3.4 Update Tenant Details
* **URL**: `PUT https://jupiter.nearle.app/live/api/v1/tenants/update`
* **Request Body**:
  ```json
  {
    "tenantid": 8,
    "tenantname": "Sydney Premium Grocers Group",
    "status": "Active"
  }
  ```

### 3.5 Update Tenant Location Details (V1)
* **URL**: `PUT https://jupiter.nearle.app/live/api/v1/tenants/updatelocation`
* **Request Body**:
  ```json
  {
    "locationid": 45,
    "tenantid": 8,
    "locationname": "North Sydney Hub Store",
    "address": "45 Berry St",
    "suburb": "North Sydney",
    "city": "Sydney",
    "state": "NSW",
    "postcode": "2060",
    "latitude": "-33.8398",
    "longitude": "151.2058",
    "status": "Active"
  }
  ```

### 3.6 Create Partner Association (Console)
* **URL**: `PUT https://jupiter.nearle.app/live/api/v1/tenants/createpartneruser`
* **Request Body**:
  ```json
  {
    "tenantid": 8,
    "partnerid": 102,
    "status": "Active"
  }
  ```

### 3.7 Add Customer to Tenant Database
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/tenants/createtenantcustomer`
* **Request Body**:
  ```json
  {
    "tenantid": 8,
    "customerid": 4082,
    "status": "Active"
  }
  ```

### 3.8 Add Tenant Roster Staff
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/tenants/createstaff`
* **Request Body**:
  ```json
  {
    "userid": 15,
    "tenantid": 8,
    "locationid": 45,
    "status": "Active"
  }
  ```

### 3.9 Update Tenant Roster Staff
* **URL**: `PUT https://jupiter.nearle.app/live/api/v1/tenants/updatestaff`
* **Request Body**:
  ```json
  {
    "userid": 15,
    "tenantid": 8,
    "locationid": 45,
    "status": "Inactive"
  }
  ```

### 3.10 Create Delivery Rate Config for Tenant
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/tenants/createpricing`
* **Request Body**:
  ```json
  {
    "tenantid": 8,
    "basefare": 8.50,
    "additionalkm": 1.50,
    "additionalcharges": 2.00,
    "fuelcharge": 0.50
  }
  ```

### 3.11 Create Tenant Support Request ticket
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/tenants/createtenantrequest`
* **Request Body**:
  ```json
  {
    "tenantid": 8,
    "subject": "Payout mismatch on invoice INV-00802",
    "description": "Calculated payout did not include fuel tax bonus.",
    "category": "Billing"
  }
  ```

### 3.12 Create Tenant Discount Promotion Configuration
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/tenants/createtenantpromotions`
* **Request Body**:
  ```json
  {
    "tenantid": 8,
    "promocode": "FREESHIP50",
    "discountamount": 10.00,
    "minordervalue": 50.00,
    "status": "Active"
  }
  ```

### 3.13 Create Tenant physical outlet (V2)
* **URL**: `POST https://jupiter.nearle.app/live/api/v2/tenants/createtenantlocation`
* **Request Body**: See V1 location request payload structure.

### 3.14 Update Tenant Physical Location Details (V2)
* **URL**: `PUT https://jupiter.nearle.app/live/api/v2/tenants/updatetenantlocation`
* **Request Body**: See V1 location request payload structure.

---

## 4. 📦 Products & Catalog APIs

### 4.1 Create Catalog Product
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/products/create`
* **Request Body**:
  ```json
  {
    "productid": 0,
    "productname": "Organic Strawberries 500g",
    "categoryid": 4,
    "subcategoryid": 14,
    "tenantid": 8,
    "applocationid": 5,
    "productcost": 6.80,
    "unitvalue": "500g",
    "productstatus": "available",
    "sku": "STRAW-500G-ORG",
    "status": "Active"
  }
  ```

### 4.2 Update Product Attributes
* **URL**: `PUT https://jupiter.nearle.app/live/api/v1/products/update`
* **Request Body**:
  ```json
  {
    "productid": 101,
    "productname": "Premium Organic Strawberries 500g",
    "categoryid": 4,
    "subcategoryid": 14,
    "tenantid": 8,
    "applocationid": 5,
    "productcost": 7.20,
    "unitvalue": "500g",
    "productstatus": "available",
    "sku": "STRAW-500G-ORG",
    "status": "Active"
  }
  ```

### 4.3 Delete Product
* **URL**: `DELETE https://jupiter.nearle.app/live/api/v1/products/delete`
* **Request Body**:
  ```json
  {
    "productid": 101
  }
  ```

### 4.4 Create Product Variant
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/products/createproductvariant`
* **Request Body**:
  ```json
  {
    "productid": 101,
    "variantname": "Mega Pack 1Kg",
    "variantcost": 12.50,
    "sku": "STRAW-1KG-ORG",
    "status": "Active"
  }
  ```

### 4.5 Setup Product Discount Rule
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/products/createproductdiscount`
* **Request Body**:
  ```json
  {
    "productid": 101,
    "discountpercentage": 15.00,
    "status": "Active"
  }
  ```

### 4.6 Set Product Location Map (V2)
* **URL**: `POST https://jupiter.nearle.app/live/api/v2/products/createproductlocation`
* **Request Body**:
  ```json
  [
    {
      "productid": 101,
      "locationid": 45,
      "tenantid": 8,
      "status": "Active"
    }
  ]
  ```

### 4.7 Update Product Location Map (V2)
* **URL**: `PUT https://jupiter.nearle.app/live/api/v2/products/updateproductlocation`
* **Request Body**:
  ```json
  {
    "productid": 101,
    "locationid": 45,
    "status": "Inactive"
  }
  ```

### 4.8 Add Stock Entry (Inbound/Outbound Ingest - V2)
* **URL**: `POST https://jupiter.nearle.app/live/api/v2/products/createproductstock`
* **Request Body**:
  ```json
  [
    {
      "stockid": 0,
      "productid": 101,
      "locationid": 45,
      "tenantid": 8,
      "qty": 50,
      "transactiontype": "in",
      "reference": "PURCHASE-PO9812",
      "createdby": 12
    }
  ]
  ```

### 4.9 Update Product Stock Quantity (V2)
* **URL**: `PUT https://jupiter.nearle.app/live/api/v2/products/updateproductstock`
* **Request Body**:
  ```json
  {
    "productid": 101,
    "locationid": 45,
    "tenantid": 8,
    "qty": 45,
    "transactiontype": "out",
    "reference": "ADJUSTMENT-RECON",
    "createdby": 12
  }
  ```

---

## 5. 🛒 Order Management APIs

### 5.1 Create Simple Order (V1)
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/orders/createorder`
* **Request Body**:
  ```json
  {
    "orders": {
      "tenantid": 8,
      "locationid": 45,
      "customerid": 4082,
      "orderamount": 13.60,
      "itemcount": 2,
      "items": [
        {
          "productid": 101,
          "productname": "Organic Strawberries 500g",
          "orderqty": 2.0,
          "unitprice": 6.80
        }
      ]
    }
  }
  ```

### 5.2 Create Multiple Orders in Bulk (V1)
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/orders/createorders`
* **Request Body**:
  ```json
  [
    {
      "orders": {
        "tenantid": 8,
        "locationid": 45,
        "customerid": 4082,
        "orderamount": 6.80,
        "itemcount": 1,
        "items": [ ... ]
      }
    }
  ]
  ```

### 5.3 Update Order Details
* **URL**: `PUT https://jupiter.nearle.app/live/api/v1/orders/updateorder`
* **Request Body**:
  ```json
  {
    "orderheaderid": 9821,
    "orderstatus": "delivered",
    "deliveryamt": 12.50
  }
  ```

### 5.4 Update Multiple Orders Status in Bulk
* **URL**: `PUT https://jupiter.nearle.app/live/api/v1/orders/updatemultipleorders`
* **Request Body**:
  ```json
  [
    {
      "orderheaderid": 9821,
      "orderstatus": "picked"
    },
    {
      "orderheaderid": 9822,
      "orderstatus": "picked"
    }
  ]
  ```

### 5.5 Create Order with Coordinates Details (V2)
* **URL**: `POST https://jupiter.nearle.app/live/api/v2/orders/createorder`
* **Request Body**:
  ```json
  {
    "orders": {
      "tenantid": 8,
      "orderamount": 13.60,
      "itemcount": 1,
      "items": [
        {
          "productid": 101,
          "productname": "Organic Strawberries 500g",
          "orderqty": 2.0,
          "unitprice": 6.80
        }
      ]
    },
    "pickup": {
      "customerid": 15,
      "address": "Pickup Main Warehouse St",
      "latitude": "-33.8688",
      "longitude": "151.2093"
    },
    "drop": {
      "customerid": 4082,
      "address": "100 Berry St, North Sydney NSW 2060",
      "latitude": "-33.8398",
      "longitude": "151.2058"
    }
  }
  ```

### 5.6 Create Order with Auto Stock-Out Record (V3)
* **URL**: `POST https://jupiter.nearle.app/live/api/v3/orders/createorder`
* **Request Body**: See V1 order payload format.

---

## 6. 🚚 Deliveries & Dispatch APIs

### 6.1 Register New Dispatch Task (V1)
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/deliveries/createdelivery`
* **Request Body**:
  ```json
  {
    "deliveryid": 0,
    "orderheaderid": 9821,
    "userid": 12,
    "tenantid": 8,
    "orderid": "ORD-000843",
    "deliverydate": "2026-05-20",
    "orderstatus": "pending",
    "pickupaddress": "123 Warehouse Rd",
    "pickuplat": "-33.8600",
    "pickuplon": "151.2000",
    "deliveryaddress": "45 Residential St",
    "deliverylat": "-33.8700",
    "deliverylong": "151.2100",
    "deliveryamt": 12.50,
    "paymenttype": 43
  }
  ```

### 6.2 Register Bulk Dispatches (V1)
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/deliveries/createdeliveries`
* **Request Body**: Array of V1 dispatch payloads.

### 6.3 Update Transit Status (Rider state transitions V1)
* **URL**: `PUT https://jupiter.nearle.app/live/api/v1/deliveries/Updatedelivery`
* **Request Body**:
  ```json
  {
    "deliveryid": 405,
    "orderheaderid": 9821,
    "userid": 12,
    "orderstatus": "delivered",
    "starttime": "2026-05-20 10:30:00",
    "arrivaltime": "2026-05-20 10:45:00",
    "deliverytime": "2026-05-20 10:50:00",
    "riderslat": "-33.8702",
    "riderslon": "151.2103",
    "dropimage": "base64_or_s3_url_string",
    "collectedamt": 12.50,
    "collectionstatus": 1
  }
  ```

### 6.4 Publish Delivery Tracking Logs (V1)
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/deliveries/createdeliverylog`
* **Request Body**:
  ```json
  {
    "deliveryid": 405,
    "latitude": "-33.8688",
    "longitude": "151.2093",
    "raw_latitude": "-33.86885",
    "raw_longitude": "151.20935",
    "speed": "24.5",
    "heading": "180.0",
    "status": "in_transit"
  }
  ```

### 6.5 Register Bulk Dispatches (V2)
* **URL**: `POST https://jupiter.nearle.app/live/api/v2/deliveries/createdeliveries`
* **Request Body**: Array of V1 dispatch payloads.

### 6.6 Publish Delivery Tracking Logs (V2)
* **URL**: `POST https://jupiter.nearle.app/live/api/v2/deliveries/createdeliverylog`
* **Request Body**: See V1 tracking log payload.

---

## 7. 🤝 Partner & Rider Operations APIs

### 7.1 Setup Logistics Shift
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/partners/createshift`
* **Request Body**:
  ```json
  {
    "shiftid": 0,
    "shiftdate": "2026-05-20",
    "starttime": "08:00:00",
    "endtime": "16:00:00",
    "shifthours": 8.0,
    "basefare": 20.00,
    "additionalkm": 1.20,
    "additionalcharges": 2.50,
    "orders": 15,
    "fuelcharge": 5.00
  }
  ```

### 7.2 Register Logistics Rider profile
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/partners/createrider`
* **Request Body**:
  ```json
  {
    "userid": 12,
    "partnerid": 102,
    "identificationno": "AB981240A",
    "shiftid": 2,
    "basefare": 20.00,
    "additionalkm": 1.20,
    "additionalcharges": 2.50,
    "vehicleid": 3,
    "vehiclename": "Electric Bike",
    "vehicleno": "NSW-RIDER-01",
    "model": "Volt-X",
    "color": "Red",
    "licenseno": "LIC801249",
    "insuranceno": "INS-7712",
    "insurancedate": "2027-05-20"
  }
  ```

### 7.3 Update Rider Operational Rates Setup
* **URL**: `PUT https://jupiter.nearle.app/live/api/v1/partners/updateridersettings`
* **Request Body**:
  ```json
  {
    "userid": 12,
    "partnerid": 102,
    "basefare": 22.00,
    "additionalkm": 1.30,
    "additionalcharges": 3.00
  }
  ```

### 7.4 Update Rider Profile details
* **URL**: `PUT https://jupiter.nearle.app/live/api/v1/partners/updaterider`
* **Request Body**: Complete rider register model updating targeted values.

### 7.5 Create Rider Shift Log (V1 / V2)
* **URLs**:
  * `POST https://jupiter.nearle.app/live/api/v1/partners/createriderlog`
  * `POST https://jupiter.nearle.app/live/api/v2/partners/createriderlog`
* **Request Body**:
  ```json
  {
    "logid": 0,
    "logdate": "2026-05-20",
    "userid": 12,
    "partnerid": 102,
    "shiftid": 2,
    "shifthours": 8.0,
    "login": "2026-05-20 08:00:00",
    "latitude": "-33.8688",
    "longitude": "151.2093",
    "status": "login"
  }
  ```

### 7.6 Update Rider Shift Log (Logout/Fulfill - V1 / V2)
* **URLs**:
  * `PUT https://jupiter.nearle.app/live/api/v1/partners/updateriderlog`
  * `PUT https://jupiter.nearle.app/live/api/v2/partners/updateriderlog`
* **Request Body**:
  ```json
  {
    "logid": 4092,
    "userid": 12,
    "logout": "2026-05-20 16:00:00",
    "workhours": 7.8,
    "shorthours": 0.2,
    "logstatus": 2,
    "latitude": "-33.8690",
    "longitude": "151.2100",
    "status": "logout"
  }
  ```

### 7.7 Create Rider break status log (V1 / V2)
* **URLs**:
  * `POST https://jupiter.nearle.app/live/api/v1/partners/createbreaklog`
  * `POST https://jupiter.nearle.app/live/api/v2/partners/createbreaklog`
* **Request Body**:
  ```json
  {
    "breakid": 0,
    "logid": 4092,
    "breakdate": "2026-05-20",
    "userid": 12,
    "partnerid": 102,
    "shiftid": 2,
    "breakstart": "2026-05-20 12:00:00",
    "latitude": "-33.8688",
    "longitude": "151.2093"
  }
  ```

### 7.8 Complete Rider break status log (V1 / V2)
* **URLs**:
  * `PUT https://jupiter.nearle.app/live/api/v1/partners/updatebreaklog`
  * `PUT https://jupiter.nearle.app/live/api/v2/partners/updatebreaklog`
* **Request Body**:
  ```json
  {
    "breakid": 901,
    "breakend": "2026-05-20 12:30:00",
    "breakhours": 0.5
  }
  ```

### 7.9 Submit Rider support request ticket
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/partners/createridersupport`
* **Request Body**: See V1 customer support request format.

### 7.10 Delete Rider Logs (V2)
* **URL**: `DELETE https://jupiter.nearle.app/live/api/v2/partners/deleteriderlog`
* **Request Body**:
  ```json
  {
    "logid": 4092
  }
  ```

---

## 8. 🧾 Invoices & Billing APIs

### 8.1 Create Invoice Setup
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/invoice/create`
* **Request Body**:
  ```json
  {
    "invoiceid": 0,
    "invoiceno": "INV-00802",
    "invoicedate": "2026-05-20",
    "tenantid": 8,
    "customerid": 4082,
    "amount": 250.00,
    "taxamount": 25.00,
    "status": "Unpaid"
  }
  ```

### 8.2 Update Invoice
* **URL**: `PUT https://jupiter.nearle.app/live/api/v1/invoice/update`
* **Request Body**: Complete invoice model with targeting invoice ID.

### 8.3 Update Invoice Payment Status
* **URL**: `PUT https://jupiter.nearle.app/live/api/v1/invoice/updatestatus`
* **Request Body**:
  ```json
  {
    "invoiceid": 402,
    "status": "Paid",
    "paymentmode": "Card",
    "reference": "TXN9402801"
  }
  ```

---

## 9. 🛠️ Utilities & Webhooks APIs

### 9.1 Send Single Push Notification
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/utils/notifyuser`
* **Request Body**:
  ```json
  {
    "token": "FCM_DEVICE_TOKEN_ABC",
    "notification": {
      "title": "Welcome to Nearle!",
      "body": "Your registration was successful.",
      "sound": "default",
      "type": "welcome"
    }
  }
  ```

### 9.2 Send Multi-token Broadcast Push Notification
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/utils/sendnotifications`
* **Request Body**:
  ```json
  {
    "token": ["FCM_TOKEN_1", "FCM_TOKEN_2"],
    "notification": {
      "title": "System Update",
      "body": "System will be down for 5 mins.",
      "sound": "default",
      "type": "standard"
    }
  }
  ```

### 9.3 Create Global Logistics Rates Config
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/utils/createapppricing`
* **Request Body**: See Tenant delivery rate setup payload structure.

### 9.4 Send Push notification to Admin Console
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/utils/notifyadmin`
* **Request Body**:
  ```json
  {
    "token": "ADMIN_FCM_TOKEN",
    "notification": {
      "title": "Database Threshold",
      "body": "Active connection reaches 85%.",
      "sound": "default",
      "type": "warning"
    }
  }
  ```

### 9.5 Send Push notification to Tenant Manager & log history
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/utils/notifytenant`
* **Request Body**:
  ```json
  {
    "token": "TENANT_FCM_TOKEN",
    "tenantid": 8,
    "moduleid": 6,
    "locationid": 45,
    "customerid": 4082,
    "notification": {
      "title": "Low Stock",
      "body": "Fresh apples quantity falls below threshold.",
      "sound": "default",
      "type": "alert"
    }
  }
  ```

### 9.6 General Webhook Listener / Receiver
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/utils/webhooks`
* **Request Body**:
  ```json
  {
    "id": "event-uuid-1",
    "event": "sale.created",
    "timestamp": "2026-05-20T10:20:00Z",
    "payload": { ... }
  }
  ```

### 9.7 Third-party GraphQL Webhook Registration
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/utils/register-webhook`
* **Request Body**:
  ```json
  {
    "callbackurl": "https://jupiter.nearle.app/live/api/v1/utils/webhooksreceiver",
    "secret": "webhook_secret_key"
  }
  ```

### 9.8 Create Internal Webhook Event Configuration
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/utils/createwebhook`
* **Request Body**:
  ```json
  {
    "webhookid": 0,
    "eventname": "sale.created",
    "callbackurl": "https://clientapp.com/webhooks",
    "status": "Active"
  }
  ```

### 9.9 Shopfront Callback Webhook Receiver
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/utils/webhooksreceiver`
* **Request Body**: Accepts payload format designated by the external Shopfront service.

### 9.10 Setup Shopfront Inventory GraphQL Webhook
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/utils/webhooks/inventory`
* **Request Body**: See V1 webhook register payload format.

### 9.11 Setup physical app zone config
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/utils/createapplocationconfig`
* **Request Body**:
  ```json
  {
    "applocationid": 5,
    "configid": 6,
    "locationname": "Sydney Metro Hub",
    "latitude": "-33.8688",
    "longitude": "151.2093",
    "status": "Active"
  }
  ```

### 9.12 Update physical app zone config
* **URL**: `PUT https://jupiter.nearle.app/live/api/v1/utils/updateapplocationconfig`
* **Request Body**: See V1 app zone setup payload format.

### 9.13 Ingest App User Credentials in Redis Cache
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/utils/createuserredis`
* **Request Body**:
  ```json
  {
    "userid": 12,
    "authtoken": "session_bearer_token_string",
    "expiry": 86400
  }
  ```

### 9.14 Publish Rider Periodic Coordinates Log
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/utils/createriderperiodiclog`
* **Request Body**:
  ```json
  {
    "userid": 12,
    "latitude": "-33.8688",
    "longitude": "151.2093",
    "speed": "15.4",
    "heading": "90.0",
    "timestamp": "2026-05-20T10:20:00Z"
  }
  ```

### 9.15 Publish Rider Current Duty status
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/utils/createriderstatus`
* **Request Body**:
  ```json
  {
    "userid": 12,
    "onduty": 1,
    "status": "idle"
  }
  ```

---

## 10. 💳 Payments APIs

### 10.1 Issue Customer Payment Charge Request
* **URL**: `POST https://jupiter.nearle.app/live/api/v1/payments/requests/create`
* **Request Body**:
  ```json
  {
    "amount": 250.00,
    "currency": "AUD",
    "customerid": 4082,
    "description": "Invoice Payment INV-00802"
  }
  ```