Order Management

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2025-10-25
Version: v1.0

Base URL: https://api.nextgate.com/api/v1

Short Description

The Order Management API handles the complete order lifecycle for the NextGate e-commerce platform. It supports multiple purchase types (direct purchase, cart purchase, installment plans, and group purchases), order tracking, shipping management, and secure delivery confirmation with escrow integration.

Hints

Authentication Required: All endpoints require Bearer token authentication
Rate Limiting: 100 requests per minute per user
Order Sources: Supports DIRECT_PURCHASE, CART_PURCHASE, INSTALLMENT, and GROUP_PURCHASE
Delivery Confirmation: Uses secure 6-digit codes with SHA-256 hashing and salt
Escrow Integration: Automatic escrow hold and release on delivery confirmation
Pagination: Default page size is 10, maximum is 50
Timezone: All timestamps are in ISO 8601 format (UTC)
Currency: All amounts are in TZS (Tanzanian Shilling) with 2 decimal precision

Standard Response Format

All API responses follow a consistent structure using the Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-10-25T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-10-25T10:30:45",
  "data": "Error description"
}

Standard Response Fields

Field	Type	Description
success	boolean	Always true for successful operations, false for errors
httpStatus	string	HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.)
message	string	Human-readable message describing the operation result
action_time	string	ISO 8601 timestamp of when the response was generated
data	object/string	Response payload for success, error details for failures

HTTP Method Badge Standards

For better visual clarity, all endpoints use colored badges for HTTP methods:

GET - Green (Safe, read-only operations)
POST - Blue (Create new resources)
PUT - Yellow (Update/replace entire resource)
PATCH - Orange (Partial updates)
DELETE - Red (Remove resources)

Endpoints

1. Get Order by ID

Purpose: Retrieve detailed information about a specific order using its UUID.

Endpoint: GET {base_url}/orders/{orderId}

Access Level: 🔒 Protected (Buyer or Seller only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
orderId	UUID	Yes	Unique identifier of the order	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Order retrieved successfully",
  "action_time": "2025-10-25T10:30:45",
  "data": {
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "orderNumber": "ORD-2025-12345",
    "buyer": {
      "accountId": "123e4567-e89b-12d3-a456-426614174000",
      "userName": "johndoe",
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    "seller": {
      "shopId": "789e0123-e45b-67d8-a901-234567890abc",
      "shopName": "TechStore",
      "shopLogo": "https://cdn.nextgate.com/shops/techstore.png",
      "shopSlug": "techstore"
    },
    "orderStatus": "SHIPPED",
    "deliveryStatus": "IN_TRANSIT",
    "orderSource": "DIRECT_PURCHASE",
    "items": [
      {
        "orderItemId": "111e2222-e33b-44d5-a666-777788889999",
        "productId": "abc12345-def6-7890-ghij-klmnopqrstuv",
        "productName": "Wireless Headphones",
        "productSlug": "wireless-headphones",
        "productImage": "https://cdn.nextgate.com/products/headphones.jpg",
        "quantity": 2,
        "unitPrice": 85000.00,
        "subtotal": 170000.00,
        "tax": 0.00,
        "total": 170000.00
      }
    ],
    "subtotal": 170000.00,
    "shippingFee": 5000.00,
    "tax": 0.00,
    "totalAmount": 175000.00,
    "platformFee": 8750.00,
    "sellerAmount": 166250.00,
    "currency": "TZS",
    "paymentMethod": "MPESA",
    "amountPaid": 175000.00,
    "amountRemaining": 0.00,
    "deliveryAddress": "123 Main St, Dar es Salaam, Tanzania",
    "trackingNumber": "TRACK-550E8400",
    "carrier": "NextGate Shipping",
    "isDeliveryConfirmed": false,
    "deliveryConfirmedAt": null,
    "orderedAt": "2025-10-20T14:30:00",
    "shippedAt": "2025-10-21T09:15:00",
    "deliveredAt": null,
    "cancelledAt": null,
    "cancellationReason": null
  }
}

Success Response Fields:

Field	Description
orderId	Unique identifier of the order
orderNumber	Human-readable order number (format: ORD-YYYY-XXXXX)
buyer	Object containing buyer account information
seller	Object containing shop/seller information
orderStatus	Current status (PENDING_PAYMENT, PENDING_SHIPMENT, SHIPPED, DELIVERED, COMPLETED, CANCELLED, REFUNDED)
deliveryStatus	Delivery tracking status (PENDING, SHIPPED, IN_TRANSIT, DELIVERED, CONFIRMED)
orderSource	Purchase type (DIRECT_PURCHASE, CART_PURCHASE, INSTALLMENT, GROUP_PURCHASE)
items	Array of order items with product details
subtotal	Sum of all item totals before shipping and tax
shippingFee	Shipping cost
tax	Tax amount
totalAmount	Final amount (subtotal + shipping + tax)
platformFee	Platform commission (5% of total)
sellerAmount	Amount seller receives after platform fee
currency	Currency code (TZS)
isDeliveryConfirmed	Whether buyer confirmed delivery
trackingNumber	Shipping tracking number
orderedAt	Order creation timestamp
shippedAt	Shipping timestamp
deliveredAt	Delivery timestamp

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Order not found: 550e8400-e29b-41d4-a716-446655440000",
  "action_time": "2025-10-25T10:30:45",
  "data": "Order not found: 550e8400-e29b-41d4-a716-446655440000"
}

Standard Error Types:

400 BAD_REQUEST: Access denied - user is not buyer or seller of this order
401 UNAUTHORIZED: Missing or invalid authentication token
404 NOT_FOUND: Order does not exist

2. Get Order by Order Number

Purpose: Retrieve order details using the human-readable order number.

Endpoint: GET {base_url}/orders/number/{orderNumber}

Access Level: 🔒 Protected (Buyer or Seller only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
orderNumber	string	Yes	Human-readable order number	Format: ORD-YYYY-XXXXX

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Order retrieved successfully",
  "action_time": "2025-10-25T10:30:45",
  "data": {
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "orderNumber": "ORD-2025-12345",
    "buyer": {
      "accountId": "123e4567-e89b-12d3-a456-426614174000",
      "userName": "johndoe",
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    "seller": {
      "shopId": "789e0123-e45b-67d8-a901-234567890abc",
      "shopName": "TechStore",
      "shopLogo": "https://cdn.nextgate.com/shops/techstore.png",
      "shopSlug": "techstore"
    },
    "orderStatus": "PENDING_SHIPMENT",
    "deliveryStatus": "PENDING",
    "orderSource": "CART_PURCHASE",
    "items": [
      {
        "orderItemId": "111e2222-e33b-44d5-a666-777788889999",
        "productId": "abc12345-def6-7890-ghij-klmnopqrstuv",
        "productName": "Smart Watch",
        "productSlug": "smart-watch",
        "productImage": "https://cdn.nextgate.com/products/watch.jpg",
        "quantity": 1,
        "unitPrice": 250000.00,
        "subtotal": 250000.00,
        "tax": 0.00,
        "total": 250000.00
      }
    ],
    "subtotal": 250000.00,
    "shippingFee": 8000.00,
    "tax": 0.00,
    "totalAmount": 258000.00,
    "platformFee": 12900.00,
    "sellerAmount": 245100.00,
    "currency": "TZS",
    "paymentMethod": "TIGOPESA",
    "amountPaid": 258000.00,
    "amountRemaining": 0.00,
    "deliveryAddress": "456 Commerce Road, Arusha, Tanzania",
    "trackingNumber": null,
    "carrier": null,
    "isDeliveryConfirmed": false,
    "deliveryConfirmedAt": null,
    "orderedAt": "2025-10-25T08:20:00",
    "shippedAt": null,
    "deliveredAt": null,
    "cancelledAt": null,
    "cancellationReason": null
  }
}

Success Response Fields:

Field	Description
Same as Get Order by ID	All fields identical to endpoint #1

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Order not found: ORD-2025-12345",
  "action_time": "2025-10-25T10:30:45",
  "data": "Order not found: ORD-2025-12345"
}

Standard Error Types:

400 BAD_REQUEST: Access denied - user is not buyer or seller of this order
401 UNAUTHORIZED: Missing or invalid authentication token
404 NOT_FOUND: Order with specified order number does not exist

3. Get My Orders (Customer)

Purpose: Retrieve all orders for the authenticated customer.

Endpoint: GET {base_url}/orders/my-orders

Access Level: 🔒 Protected (Customer only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Orders retrieved successfully",
  "action_time": "2025-10-25T10:30:45",
  "data": [
    {
      "orderId": "550e8400-e29b-41d4-a716-446655440000",
      "orderNumber": "ORD-2025-12345",
      "buyer": {
        "accountId": "123e4567-e89b-12d3-a456-426614174000",
        "userName": "johndoe",
        "email": "john@example.com",
        "firstName": "John",
        "lastName": "Doe"
      },
      "seller": {
        "shopId": "789e0123-e45b-67d8-a901-234567890abc",
        "shopName": "TechStore",
        "shopLogo": "https://cdn.nextgate.com/shops/techstore.png",
        "shopSlug": "techstore"
      },
      "orderStatus": "SHIPPED",
      "deliveryStatus": "IN_TRANSIT",
      "orderSource": "DIRECT_PURCHASE",
      "items": [
        {
          "orderItemId": "111e2222-e33b-44d5-a666-777788889999",
          "productId": "abc12345-def6-7890-ghij-klmnopqrstuv",
          "productName": "Wireless Headphones",
          "productSlug": "wireless-headphones",
          "productImage": "https://cdn.nextgate.com/products/headphones.jpg",
          "quantity": 2,
          "unitPrice": 85000.00,
          "subtotal": 170000.00,
          "tax": 0.00,
          "total": 170000.00
        }
      ],
      "subtotal": 170000.00,
      "shippingFee": 5000.00,
      "tax": 0.00,
      "totalAmount": 175000.00,
      "platformFee": 8750.00,
      "sellerAmount": 166250.00,
      "currency": "TZS",
      "paymentMethod": "MPESA",
      "amountPaid": 175000.00,
      "amountRemaining": 0.00,
      "deliveryAddress": "123 Main St, Dar es Salaam, Tanzania",
      "trackingNumber": "TRACK-550E8400",
      "carrier": "NextGate Shipping",
      "isDeliveryConfirmed": false,
      "deliveryConfirmedAt": null,
      "orderedAt": "2025-10-20T14:30:00",
      "shippedAt": "2025-10-21T09:15:00",
      "deliveredAt": null,
      "cancelledAt": null,
      "cancellationReason": null
    }
  ]
}

Success Response Fields:

Field	Description
data	Array of order objects, ordered by orderedAt descending (newest first)

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "User not authenticated",
  "action_time": "2025-10-25T10:30:45",
  "data": "User not authenticated"
}

Standard Error Types:

401 UNAUTHORIZED: Missing or invalid authentication token
404 NOT_FOUND: User account not found

4. Get My Orders by Status (Customer)

Purpose: Retrieve customer orders filtered by specific order status.

Endpoint: GET {base_url}/orders/my-orders/status/{status}

Access Level: 🔒 Protected (Customer only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
status	enum	Yes	Order status to filter by	Must be: PENDING_PAYMENT, PENDING_SHIPMENT, SHIPPED, DELIVERED, COMPLETED, CANCELLED, or REFUNDED

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Orders retrieved successfully",
  "action_time": "2025-10-25T10:30:45",
  "data": [
    {
      "orderId": "550e8400-e29b-41d4-a716-446655440000",
      "orderNumber": "ORD-2025-12345",
      "buyer": {
        "accountId": "123e4567-e89b-12d3-a456-426614174000",
        "userName": "johndoe",
        "email": "john@example.com",
        "firstName": "John",
        "lastName": "Doe"
      },
      "seller": {
        "shopId": "789e0123-e45b-67d8-a901-234567890abc",
        "shopName": "TechStore",
        "shopLogo": "https://cdn.nextgate.com/shops/techstore.png",
        "shopSlug": "techstore"
      },
      "orderStatus": "SHIPPED",
      "deliveryStatus": "IN_TRANSIT",
      "orderSource": "CART_PURCHASE",
      "items": [
        {
          "orderItemId": "111e2222-e33b-44d5-a666-777788889999",
          "productId": "abc12345-def6-7890-ghij-klmnopqrstuv",
          "productName": "Laptop Bag",
          "productSlug": "laptop-bag",
          "productImage": "https://cdn.nextgate.com/products/bag.jpg",
          "quantity": 1,
          "unitPrice": 45000.00,
          "subtotal": 45000.00,
          "tax": 0.00,
          "total": 45000.00
        }
      ],
      "subtotal": 45000.00,
      "shippingFee": 3000.00,
      "tax": 0.00,
      "totalAmount": 48000.00,
      "platformFee": 2400.00,
      "sellerAmount": 45600.00,
      "currency": "TZS",
      "paymentMethod": "AIRTEL_MONEY",
      "amountPaid": 48000.00,
      "amountRemaining": 0.00,
      "deliveryAddress": "789 Business Ave, Mwanza, Tanzania",
      "trackingNumber": "TRACK-550E8401",
      "carrier": "NextGate Shipping",
      "isDeliveryConfirmed": false,
      "deliveryConfirmedAt": null,
      "orderedAt": "2025-10-24T11:45:00",
      "shippedAt": "2025-10-25T07:30:00",
      "deliveredAt": null,
      "cancelledAt": null,
      "cancellationReason": null
    }
  ]
}

Success Response Fields:

Field	Description
data	Array of order objects with matching status, ordered by orderedAt descending

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Invalid order status: INVALID_STATUS",
  "action_time": "2025-10-25T10:30:45",
  "data": "Invalid order status: INVALID_STATUS"
}

Standard Error Types:

400 BAD_REQUEST: Invalid status value provided
401 UNAUTHORIZED: Missing or invalid authentication token
404 NOT_FOUND: User account not found

5. Get My Orders with Pagination (Customer)

Purpose: Retrieve customer orders with pagination support for better performance.

Endpoint: GET {base_url}/orders/my-orders/paged

Access Level: 🔒 Protected (Customer only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-based)	Must be >= 1	1
size	integer	No	Number of items per page	Must be > 0, max 50	10

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Orders retrieved successfully",
  "action_time": "2025-10-25T10:30:45",
  "data": {
    "orders": [
      {
        "orderId": "550e8400-e29b-41d4-a716-446655440000",
        "orderNumber": "ORD-2025-12345",
        "buyer": {
          "accountId": "123e4567-e89b-12d3-a456-426614174000",
          "userName": "johndoe",
          "email": "john@example.com",
          "firstName": "John",
          "lastName": "Doe"
        },
        "seller": {
          "shopId": "789e0123-e45b-67d8-a901-234567890abc",
          "shopName": "TechStore",
          "shopLogo": "https://cdn.nextgate.com/shops/techstore.png",
          "shopSlug": "techstore"
        },
        "orderStatus": "COMPLETED",
        "deliveryStatus": "CONFIRMED",
        "orderSource": "DIRECT_PURCHASE",
        "items": [
          {
            "orderItemId": "111e2222-e33b-44d5-a666-777788889999",
            "productId": "abc12345-def6-7890-ghij-klmnopqrstuv",
            "productName": "USB Cable",
            "productSlug": "usb-cable",
            "productImage": "https://cdn.nextgate.com/products/cable.jpg",
            "quantity": 3,
            "unitPrice": 5000.00,
            "subtotal": 15000.00,
            "tax": 0.00,
            "total": 15000.00
          }
        ],
        "subtotal": 15000.00,
        "shippingFee": 2000.00,
        "tax": 0.00,
        "totalAmount": 17000.00,
        "platformFee": 850.00,
        "sellerAmount": 16150.00,
        "currency": "TZS",
        "paymentMethod": "MPESA",
        "amountPaid": 17000.00,
        "amountRemaining": 0.00,
        "deliveryAddress": "321 Tech Road, Dodoma, Tanzania",
        "trackingNumber": "TRACK-550E8402",
        "carrier": "NextGate Shipping",
        "isDeliveryConfirmed": true,
        "deliveryConfirmedAt": "2025-10-23T16:20:00",
        "orderedAt": "2025-10-20T10:15:00",
        "shippedAt": "2025-10-21T08:00:00",
        "deliveredAt": "2025-10-23T16:20:00",
        "cancelledAt": null,
        "cancellationReason": null
      }
    ],
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 25,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": false
  }
}

Success Response Fields:

Field	Description
orders	Array of order objects for current page
currentPage	Current page number (1-based)
pageSize	Number of items per page
totalElements	Total number of orders across all pages
totalPages	Total number of pages available
hasNext	Whether there is a next page
hasPrevious	Whether there is a previous page
isFirst	Whether this is the first page
isLast	Whether this is the last page

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Invalid pagination parameters",
  "action_time": "2025-10-25T10:30:45",
  "data": "Page must be >= 1 and size must be > 0"
}

Standard Error Types:

400 BAD_REQUEST: Invalid page or size parameters
401 UNAUTHORIZED: Missing or invalid authentication token
404 NOT_FOUND: User account not found

6. Get My Orders by Status with Pagination (Customer)

Purpose: Retrieve customer orders filtered by status with pagination support.

Endpoint: GET {base_url}/orders/my-orders/status/{status}/paged

Access Level: 🔒 Protected (Customer only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
status	enum	Yes	Order status to filter by	Must be: PENDING_PAYMENT, PENDING_SHIPMENT, SHIPPED, DELIVERED, COMPLETED, CANCELLED, or REFUNDED

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-based)	Must be >= 1	1
size	integer	No	Number of items per page	Must be > 0, max 50	10

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Orders retrieved successfully",
  "action_time": "2025-10-25T10:30:45",
  "data": {
    "orders": [
      {
        "orderId": "550e8400-e29b-41d4-a716-446655440000",
        "orderNumber": "ORD-2025-12345",
        "buyer": {
          "accountId": "123e4567-e89b-12d3-a456-426614174000",
          "userName": "johndoe",
          "email": "john@example.com",
          "firstName": "John",
          "lastName": "Doe"
        },
        "seller": {
          "shopId": "789e0123-e45b-67d8-a901-234567890abc",
          "shopName": "TechStore",
          "shopLogo": "https://cdn.nextgate.com/shops/techstore.png",
          "shopSlug": "techstore"
        },
        "orderStatus": "SHIPPED",
        "deliveryStatus": "IN_TRANSIT",
        "orderSource": "INSTALLMENT",
        "items": [
          {
            "orderItemId": "111e2222-e33b-44d5-a666-777788889999",
            "productId": "abc12345-def6-7890-ghij-klmnopqrstuv",
            "productName": "Gaming Console",
            "productSlug": "gaming-console",
            "productImage": "https://cdn.nextgate.com/products/console.jpg",
            "quantity": 1,
            "unitPrice": 500000.00,
            "subtotal": 500000.00,
            "tax": 0.00,
            "total": 500000.00
          }
        ],
        "subtotal": 500000.00,
        "shippingFee": 10000.00,
        "tax": 0.00,
        "totalAmount": 510000.00,
        "platformFee": 25500.00,
        "sellerAmount": 484500.00,
        "currency": "TZS",
        "paymentMethod": "MPESA",
        "amountPaid": 153000.00,
        "amountRemaining": 357000.00,
        "deliveryAddress": "555 Gaming Street, Dar es Salaam, Tanzania",
        "trackingNumber": "TRACK-550E8403",
        "carrier": "NextGate Shipping",
        "isDeliveryConfirmed": false,
        "deliveryConfirmedAt": null,
        "orderedAt": "2025-10-23T13:00:00",
        "shippedAt": "2025-10-24T10:30:00",
        "deliveredAt": null,
        "cancelledAt": null,
        "cancellationReason": null
      }
    ],
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 8,
    "totalPages": 1,
    "hasNext": false,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": true
  }
}

Success Response Fields:

Field	Description
orders	Array of order objects matching status for current page
currentPage	Current page number (1-based)
pageSize	Number of items per page
totalElements	Total number of matching orders across all pages
totalPages	Total number of pages available
hasNext	Whether there is a next page
hasPrevious	Whether there is a previous page
isFirst	Whether this is the first page
isLast	Whether this is the last page

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Invalid order status: INVALID_STATUS",
  "action_time": "2025-10-25T10:30:45",
  "data": "Invalid order status: INVALID_STATUS"
}

Standard Error Types:

400 BAD_REQUEST: Invalid status value or pagination parameters
401 UNAUTHORIZED: Missing or invalid authentication token
404 NOT_FOUND: User account not found

7. Get Shop Orders (Non-Paginated)

Purpose: Retrieve all orders for a specific shop (shop owner only).

Endpoint: GET {base_url}/orders/shop/{shopId}/orders

Access Level: 🔒 Protected (Shop Owner only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Orders retrieved successfully",
  "action_time": "2025-10-25T10:30:45",
  "data": [
    {
      "orderId": "550e8400-e29b-41d4-a716-446655440000",
      "orderNumber": "ORD-2025-12345",
      "buyer": {
        "accountId": "123e4567-e89b-12d3-a456-426614174000",
        "userName": "johndoe",
        "email": "john@example.com",
        "firstName": "John",
        "lastName": "Doe"
      },
      "seller": {
        "shopId": "789e0123-e45b-67d8-a901-234567890abc",
        "shopName": "TechStore",
        "shopLogo": "https://cdn.nextgate.com/shops/techstore.png",
        "shopSlug": "techstore"
      },
      "orderStatus": "PENDING_SHIPMENT",
      "deliveryStatus": "PENDING",
      "orderSource": "DIRECT_PURCHASE",
      "items": [
        {
          "orderItemId": "111e2222-e33b-44d5-a666-777788889999",
          "productId": "abc12345-def6-7890-ghij-klmnopqrstuv",
          "productName": "Keyboard",
          "productSlug": "keyboard",
          "productImage": "https://cdn.nextgate.com/products/keyboard.jpg",
          "quantity": 1,
          "unitPrice": 75000.00,
          "subtotal": 75000.00,
          "tax": 0.00,
          "total": 75000.00
        }
      ],
      "subtotal": 75000.00,
      "shippingFee": 4000.00,
      "tax": 0.00,
      "totalAmount": 79000.00,
      "platformFee": 3950.00,
      "sellerAmount": 75050.00,
      "currency": "TZS",
      "paymentMethod": "TIGOPESA",
      "amountPaid": 79000.00,
      "amountRemaining": 0.00,
      "deliveryAddress": "123 Office Complex, Morogoro, Tanzania",
      "trackingNumber": null,
      "carrier": null,
      "isDeliveryConfirmed": false,
      "deliveryConfirmedAt": null,
      "orderedAt": "2025-10-25T09:00:00",
      "shippedAt": null,
      "deliveredAt": null,
      "cancelledAt": null,
      "cancellationReason": null
    }
  ]
}

Success Response Fields:

Field	Description
data	Array of all order objects for the shop, ordered by orderedAt descending

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Access denied. You are not the owner of this shop",
  "action_time": "2025-10-25T10:30:45",
  "data": "Access denied. You are not the owner of this shop"
}

Standard Error Types:

400 BAD_REQUEST: User is not the owner of the specified shop
401 UNAUTHORIZED: Missing or invalid authentication token
404 NOT_FOUND: Shop not found or has been deleted

8. Get Shop Orders by Status (Non-Paginated)

Purpose: Retrieve shop orders filtered by specific order status.

Endpoint: GET {base_url}/orders/shop/{shopId}/orders/status/{status}

Access Level: 🔒 Protected (Shop Owner only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Valid UUID format
status	enum	Yes	Order status to filter by	Must be: PENDING_PAYMENT, PENDING_SHIPMENT, SHIPPED, DELIVERED, COMPLETED, CANCELLED, or REFUNDED

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Orders retrieved successfully",
  "action_time": "2025-10-25T10:30:45",
  "data": [
    {
      "orderId": "550e8400-e29b-41d4-a716-446655440000",
      "orderNumber": "ORD-2025-12345",
      "buyer": {
        "accountId": "123e4567-e89b-12d3-a456-426614174000",
        "userName": "johndoe",
        "email": "john@example.com",
        "firstName": "John",
        "lastName": "Doe"
      },
      "seller": {
        "shopId": "789e0123-e45b-67d8-a901-234567890abc",
        "shopName": "TechStore",
        "shopLogo": "https://cdn.nextgate.com/shops/techstore.png",
        "shopSlug": "techstore"
      },
      "orderStatus": "PENDING_SHIPMENT",
      "deliveryStatus": "PENDING",
      "orderSource": "GROUP_PURCHASE",
      "items": [
        {
          "orderItemId": "111e2222-e33b-44d5-a666-777788889999",
          "productId": "abc12345-def6-7890-ghij-klmnopqrstuv",
          "productName": "Phone Case",
          "productSlug": "phone-case",
          "productImage": "https://cdn.nextgate.com/products/case.jpg",
          "quantity": 1,
          "unitPrice": 12000.00,
          "subtotal": 12000.00,
          "tax": 0.00,
          "total": 12000.00
        }
      ],
      "subtotal": 12000.00,
      "shippingFee": 2000.00,
      "tax": 0.00,
      "totalAmount": 14000.00,
      "platformFee": 700.00,
      "sellerAmount": 13300.00,
      "currency": "TZS",
      "paymentMethod": "MPESA",
      "amountPaid": 14000.00,
      "amountRemaining": 0.00,
      "deliveryAddress": "999 Group Buy Lane, Mbeya, Tanzania",
      "trackingNumber": null,
      "carrier": null,
      "isDeliveryConfirmed": false,
      "deliveryConfirmedAt": null,
      "orderedAt": "2025-10-25T08:45:00",
      "shippedAt": null,
      "deliveredAt": null,
      "cancelledAt": null,
      "cancellationReason": null
    }
  ]
}

Success Response Fields:

Field	Description
data	Array of order objects matching status for the shop, ordered by orderedAt descending

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Invalid order status: INVALID_STATUS",
  "action_time": "2025-10-25T10:30:45",
  "data": "Invalid order status: INVALID_STATUS"
}

Standard Error Types:

400 BAD_REQUEST: Invalid status value or user is not shop owner
401 UNAUTHORIZED: Missing or invalid authentication token
404 NOT_FOUND: Shop not found or has been deleted

9. Get Shop Orders with Pagination

Purpose: Retrieve shop orders with pagination support for better performance.

Endpoint: GET {base_url}/orders/shop/{shopId}/orders/paged

Access Level: 🔒 Protected (Shop Owner only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Valid UUID format

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-based)	Must be >= 1	1
size	integer	No	Number of items per page	Must be > 0, max 50	10

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Orders retrieved successfully",
  "action_time": "2025-10-25T10:30:45",
  "data": {
    "orders": [
      {
        "orderId": "550e8400-e29b-41d4-a716-446655440000",
        "orderNumber": "ORD-2025-12345",
        "buyer": {
          "accountId": "123e4567-e89b-12d3-a456-426614174000",
          "userName": "johndoe",
          "email": "john@example.com",
          "firstName": "John",
          "lastName": "Doe"
        },
        "seller": {
          "shopId": "789e0123-e45b-67d8-a901-234567890abc",
          "shopName": "TechStore",
          "shopLogo": "https://cdn.nextgate.com/shops/techstore.png",
          "shopSlug": "techstore"
        },
        "orderStatus": "SHIPPED",
        "deliveryStatus": "IN_TRANSIT",
        "orderSource": "CART_PURCHASE",
        "items": [
          {
            "orderItemId": "111e2222-e33b-44d5-a666-777788889999",
            "productId": "abc12345-def6-7890-ghij-klmnopqrstuv",
            "productName": "Monitor",
            "productSlug": "monitor",
            "productImage": "https://cdn.nextgate.com/products/monitor.jpg",
            "quantity": 1,
            "unitPrice": 350000.00,
            "subtotal": 350000.00,
            "tax": 0.00,
            "total": 350000.00
          }
        ],
        "subtotal": 350000.00,
        "shippingFee": 15000.00,
        "tax": 0.00,
        "totalAmount": 365000.00,
        "platformFee": 18250.00,
        "sellerAmount": 346750.00,
        "currency": "TZS",
        "paymentMethod": "MPESA",
        "amountPaid": 365000.00,
        "amountRemaining": 0.00,
        "deliveryAddress": "777 Tech Hub, Dar es Salaam, Tanzania",
        "trackingNumber": "TRACK-550E8404",
        "carrier": "NextGate Shipping",
        "isDeliveryConfirmed": false,
        "deliveryConfirmedAt": null,
        "orderedAt": "2025-10-24T15:20:00",
        "shippedAt": "2025-10-25T09:00:00",
        "deliveredAt": null,
        "cancelledAt": null,
        "cancellationReason": null
      }
    ],
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 42,
    "totalPages": 5,
    "hasNext": true,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": false
  }
}

Success Response Fields:

Field	Description
orders	Array of order objects for current page
currentPage	Current page number (1-based)
pageSize	Number of items per page
totalElements	Total number of shop orders across all pages
totalPages	Total number of pages available
hasNext	Whether there is a next page
hasPrevious	Whether there is a previous page
isFirst	Whether this is the first page
isLast	Whether this is the last page

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Access denied. You are not the owner of this shop",
  "action_time": "2025-10-25T10:30:45",
  "data": "Access denied. You are not the owner of this shop"
}

Standard Error Types:

400 BAD_REQUEST: Invalid pagination parameters or user is not shop owner
401 UNAUTHORIZED: Missing or invalid authentication token
404 NOT_FOUND: Shop not found or has been deleted

10. Get Shop Orders by Status with Pagination

Purpose: Retrieve shop orders filtered by status with pagination support.

Endpoint: GET {base_url}/orders/shop/{shopId}/orders/status/{status}/paged

Access Level: 🔒 Protected (Shop Owner only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Valid UUID format
status	enum	Yes	Order status to filter by	Must be: PENDING_PAYMENT, PENDING_SHIPMENT, SHIPPED, DELIVERED, COMPLETED, CANCELLED, or REFUNDED

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-based)	Must be >= 1	1
size	integer	No	Number of items per page	Must be > 0, max 50	10

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Orders retrieved successfully",
  "action_time": "2025-10-25T10:30:45",
  "data": {
    "orders": [
      {
        "orderId": "550e8400-e29b-41d4-a716-446655440000",
        "orderNumber": "ORD-2025-12345",
        "buyer": {
          "accountId": "123e4567-e89b-12d3-a456-426614174000",
          "userName": "johndoe",
          "email": "john@example.com",
          "firstName": "John",
          "lastName": "Doe"
        },
        "seller": {
          "shopId": "789e0123-e45b-67d8-a901-234567890abc",
          "shopName": "TechStore",
          "shopLogo": "https://cdn.nextgate.com/shops/techstore.png",
          "shopSlug": "techstore"
        },
        "orderStatus": "PENDING_SHIPMENT",
        "deliveryStatus": "PENDING",
        "orderSource": "DIRECT_PURCHASE",
        "items": [
          {
            "orderItemId": "111e2222-e33b-44d5-a666-777788889999",
            "productId": "abc12345-def6-7890-ghij-klmnopqrstuv",
            "productName": "Mouse Pad",
            "productSlug": "mouse-pad",
            "productImage": "https://cdn.nextgate.com/products/mousepad.jpg",
            "quantity": 2,
            "unitPrice": 8000.00,
            "subtotal": 16000.00,
            "tax": 0.00,
            "total": 16000.00
          }
        ],
        "subtotal": 16000.00,
        "shippingFee": 2000.00,
        "tax": 0.00,
        "totalAmount": 18000.00,
        "platformFee": 900.00,
        "sellerAmount": 17100.00,
        "currency": "TZS",
        "paymentMethod": "AIRTEL_MONEY",
        "amountPaid": 18000.00,
        "amountRemaining": 0.00,
        "deliveryAddress": "444 Startup Hub, Dodoma, Tanzania",
        "trackingNumber": null,
        "carrier": null,
        "isDeliveryConfirmed": false,
        "deliveryConfirmedAt": null,
        "orderedAt": "2025-10-25T07:15:00",
        "shippedAt": null,
        "deliveredAt": null,
        "cancelledAt": null,
        "cancellationReason": null
      }
    ],
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 15,
    "totalPages": 2,
    "hasNext": true,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": false
  }
}

Success Response Fields:

Field	Description
orders	Array of order objects matching status for current page
currentPage	Current page number (1-based)
pageSize	Number of items per page
totalElements	Total number of matching orders across all pages
totalPages	Total number of pages available
hasNext	Whether there is a next page
hasPrevious	Whether there is a previous page
isFirst	Whether this is the first page
isLast	Whether this is the last page

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Invalid order status: INVALID_STATUS",
  "action_time": "2025-10-25T10:30:45",
  "data": "Invalid order status: INVALID_STATUS"
}

Standard Error Types:

400 BAD_REQUEST: Invalid status value, pagination parameters, or user is not shop owner
401 UNAUTHORIZED: Missing or invalid authentication token
404 NOT_FOUND: Shop not found or has been deleted

11. Mark Order as Shipped (Seller Action)

Purpose: Allows seller to mark an order as shipped, generates delivery confirmation code, and sends notification to buyer.

Endpoint: POST {base_url}/orders/{orderId}/ship

Access Level: 🔒 Protected (Shop Owner/Seller only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
orderId	UUID	Yes	Unique identifier of the order	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Order marked as shipped",
  "action_time": "2025-10-25T10:30:45",
  "data": {
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "orderNumber": "ORD-2025-12345",
    "shippedAt": "2025-10-25T10:30:45",
    "message": "Order marked as shipped. Confirmation code sent to customer.",
    "confirmationCodeSent": true,
    "codeExpiresAt": "2025-11-24T10:30:45",
    "maxVerificationAttempts": 5
  }
}

Success Response Fields:

Field	Description
orderId	UUID of the shipped order
orderNumber	Human-readable order number
shippedAt	Timestamp when order was marked as shipped
message	Confirmation message
confirmationCodeSent	Whether confirmation code was sent to customer
codeExpiresAt	When the confirmation code expires (30 days from generation)
maxVerificationAttempts	Maximum number of code verification attempts allowed

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot ship order with status: COMPLETED. Order must be PENDING_SHIPMENT",
  "action_time": "2025-10-25T10:30:45",
  "data": "Cannot ship order with status: COMPLETED. Order must be PENDING_SHIPMENT"
}

Standard Error Types:

400 BAD_REQUEST: Order status is not PENDING_SHIPMENT, user is not the seller, or confirmation code generation failed
401 UNAUTHORIZED: Missing or invalid authentication token
404 NOT_FOUND: Order not found

12. Confirm Delivery (Customer Action)

Purpose: Allows customer to confirm order delivery using the 6-digit confirmation code, releases escrow to seller.

Endpoint: POST {base_url}/orders/{orderId}/confirm-delivery

Access Level: 🔒 Protected (Buyer/Customer only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
User-Agent	string	No	Device information for verification tracking
X-Forwarded-For	string	No	Client IP address (if behind proxy)
X-Real-IP	string	No	Real client IP address

Path Parameters:

Parameter	Type	Required	Description	Validation
orderId	UUID	Yes	Unique identifier of the order	Valid UUID format

Request JSON Sample:

{
  "confirmationCode": "123456"
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
confirmationCode	string	Yes	6-digit confirmation code sent to customer	Must be exactly 6 digits (0-9)

Success Response JSON Sample:

{
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "orderNumber": "ORD-2025-12345",
  "deliveredAt": "2025-10-25T10:30:45",
  "confirmedAt": "2025-10-25T10:30:45",
  "escrowReleased": true,
  "sellerAmount": 166250.00,
  "currency": "TZS",
  "message": "Delivery confirmed successfully. Order completed!"
}

Success Response Fields:

Field	Description
orderId	UUID of the confirmed order
orderNumber	Human-readable order number
deliveredAt	Timestamp when order was marked as delivered
confirmedAt	Timestamp when delivery was confirmed
escrowReleased	Whether escrow funds were released to seller
sellerAmount	Amount released to seller after platform fee
currency	Currency code
message	Confirmation message

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Invalid confirmation code. 4 attempts remaining.",
  "action_time": "2025-10-25T10:30:45",
  "data": "Invalid confirmation code. 4 attempts remaining."
}

Standard Error Types:

400 BAD_REQUEST: Invalid confirmation code, order status is not SHIPPED, user is not the buyer, maximum attempts exceeded, code expired, no escrow found, or escrow already released
401 UNAUTHORIZED: Missing or invalid authentication token
404 NOT_FOUND: Order not found or no active confirmation code exists
422 UNPROCESSABLE_ENTITY: Validation error on confirmation code format

13. Regenerate Confirmation Code (Customer Action)

Purpose: Allows customer to request a new delivery confirmation code if previous code was lost or expired.

Endpoint: POST {base_url}/orders/{orderId}/regenerate-code

Access Level: 🔒 Protected (Buyer/Customer only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
orderId	UUID	Yes	Unique identifier of the order	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Confirmation code regenerated successfully",
  "action_time": "2025-10-25T10:30:45",
  "data": {
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "orderNumber": "ORD-2025-12345",
    "codeSent": true,
    "destination": "email",
    "codeExpiresAt": "2025-11-24T10:30:45",
    "maxAttempts": 5,
    "message": "New confirmation code sent to your email"
  }
}

Success Response Fields:

Field	Description
orderId	UUID of the order
orderNumber	Human-readable order number
codeSent	Whether new code was successfully sent
destination	Where the code was sent (email, sms, or both)
codeExpiresAt	When the new code expires (30 days from generation)
maxAttempts	Maximum number of verification attempts allowed
message	Confirmation message

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot regenerate code. Order status: COMPLETED. Order must be SHIPPED.",
  "action_time": "2025-10-25T10:30:45",
  "data": "Cannot regenerate code. Order status: COMPLETED. Order must be SHIPPED."
}

Standard Error Types:

400 BAD_REQUEST: Order status is not SHIPPED, user is not the buyer, or delivery already confirmed
401 UNAUTHORIZED: Missing or invalid authentication token
404 NOT_FOUND: Order not found

Quick Reference Guide

HTTP Method Badge Code Templates

GET Badge:

<span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span>

POST Badge:

<span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span>

PUT Badge:

<span style="background-color: #ffc107; color: black; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span>

PATCH Badge:

<span style="background-color: #fd7e14; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PATCH</span>

DELETE Badge:

<span style="background-color: #dc3545; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">DELETE</span>

Common HTTP Status Codes

200 OK: Successful GET/PUT/PATCH request
201 Created: Successful POST request
204 No Content: Successful DELETE request
400 Bad Request: Invalid request data, business logic error, or item already exists
401 Unauthorized: Authentication required/failed (missing, invalid, expired, or malformed token)
403 Forbidden: Insufficient permissions, access denied, verification required
404 Not Found: Resource not found
422 Unprocessable Entity: Validation errors
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error

Authentication

Bearer Token: Include Authorization: Bearer your_token in headers

Order Status Flow

PENDING_PAYMENT → Payment not yet completed
PENDING_SHIPMENT → Payment completed, awaiting seller to ship
SHIPPED → Seller marked as shipped, awaiting delivery confirmation
DELIVERED → Seller claims delivery (legacy status)
COMPLETED → Customer confirmed delivery, escrow released
CANCELLED → Order cancelled
REFUNDED → Order refunded

Delivery Status Values

PENDING: Not yet shipped
SHIPPED: Seller marked as shipped
IN_TRANSIT: Package in transit (physical goods)
DELIVERED: Seller claims delivered
CONFIRMED: Buyer confirmed receipt with code

Order Source Types

DIRECT_PURCHASE: Normal buy now (full payment upfront)
CART_PURCHASE: Purchase made through shopping cart
INSTALLMENT: Pay over time with installment plan
GROUP_PURCHASE: Group buying

Data Format Standards

Dates: ISO 8601 format (2025-10-25T14:30:00Z)
Currency: TZS (Tanzanian Shilling), amounts in decimal with 2 precision
IDs: UUID format
Pagination: 1-based indexing (page 1 is first page)

Security Notes

Confirmation Codes: 6-digit numeric codes, SHA-256 hashed with salt
Code Expiry: 30 days from generation
Max Attempts: 5 verification attempts per code
IP Tracking: Verification attempts tracked by IP and device
Escrow Protection: Funds held until delivery confirmation

Pagination Best Practices

Default page size: 10 items
Maximum page size: 50 items
Always use 1-based page numbering
Check hasNext and hasPrevious for navigation
Use totalPages and totalElements for UI display

Revision #5
Created 18 October 2025 20:34:25 by Admin Qbit
Updated 11 December 2025 08:27:48 by Admin Qbit