Skip to main content

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

  1. PENDING_PAYMENT → Payment not yet completed
  2. PENDING_SHIPMENT → Payment completed, awaiting seller to ship
  3. SHIPPED → Seller marked as shipped, awaiting delivery confirmation
  4. DELIVERED → Seller claims delivery (legacy status)
  5. COMPLETED → Customer confirmed delivery, escrow released
  6. CANCELLED → Order cancelled
  7. 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

No comments to display

Back to top