Order Management

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

Base URL: https://api.nextgate.com/api/v1v1/e-commerce/orders

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),types, order tracking, shipping management, and secure delivery confirmation with 6-digit codes, escrow integration.integration, and digital product downloads.

Hints

:

• Authentication Required: All endpoints require Bearer token authentication
• Rate Limiting: 100 requests per minute per user
• Order Sources: Supportssources: DIRECT_PURCHASE, CART_PURCHASE, DIGITAL_PURCHASE, INSTALLMENT, and GROUP_PURCHASE
• Delivery Confirmation:confirmation Usesuses securea 6-digit codescode (SHA-256 hashed with SHA-256salt, hashingexpires andin salt30 days, max 5 attempts)
• EscrowDigital Integration:orders Automatichave escrowdeliveryStatus: hold and release on delivery confirmationNOT_APPLICABLE
• Pagination:Confirm-delivery Default page sizeresponse is 10,returned maximumdirectly is(not 50
• Timezone: All timestamps arewrapped 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": {
    // Actualstandard 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)envelope)

---

Endpoints

1. Get Order by ID

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

Endpoint: GET {base_url}base}/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.example.com/shops/techstore.png",
      "shopSlug": "techstore"
    },
    "orderStatus"productOrderStatus": "SHIPPED",
    "deliveryStatus": "IN_TRANSIT",
    "orderSource"productOrderSource": "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.example.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 buyerBuyer account informationinfo (accountId, userName, email, firstName, lastName)
seller	ObjectShop containinginfo shop/seller(shopId, informationshopName, shopLogo, shopSlug)
orderStatusproductOrderStatus	Current status (PENDING_PAYMENT, PENDING_SHIPMENT, SHIPPED, DELIVERED, COMPLETED, CANCELLED, REFUNDED)REFUNDED
deliveryStatus	Delivery tracking status (PENDING, SHIPPED, IN_TRANSIT, DELIVERED, CONFIRMED)CONFIRMED, NOT_APPLICABLE
orderSourceproductOrderSource	Purchase type (DIRECT_PURCHASE, CART_PURCHASE, DIGITAL_PURCHASE, INSTALLMENT, GROUP_PURCHASE)GROUP_PURCHASE
items	Array of order items with(orderItemId, productproductId, detailsproductName, productSlug, productImage, quantity, unitPrice, subtotal, tax, total)
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)
paymentMethod	Payment method used
amountPaid	Amount already paid
amountRemaining	Remaining balance (installment orders)
deliveryAddress	Shipping address
trackingNumber	Shipping tracking number (null until shipped)
carrier	Shipping carrier (null until shipped)
isDeliveryConfirmed	Whether buyer confirmed delivery
trackingNumberdeliveryConfirmedAt	ShippingTimestamp trackingof numberdelivery confirmation (null if not confirmed)
orderedAt	Order creation timestamp
shippedAt	Shipping timestamp (null until shipped)
deliveredAt	Delivery timestamp (null until delivered)
cancelledAt	Cancellation timestamp (null if not cancelled)
cancellationReason	Reason for cancellation (null if not cancelled)

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:Responses:

• 400 BAD_REQUEST:Bad Request: Access denied -— user is not buyer or seller of this order
• 401 UNAUTHORIZED:Unauthorized: MissingAuthentication or invalid authentication tokenrequired
• 404 NOT_FOUND:Not Found: Order does not existfound

---

2. Get Order by Order Number

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

Endpoint: GET {base_url}base}/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:(e.g. ORD-YYYY-XXXXX2025-12345)

SuccessResponse: ResponseSame 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
Samestructure as Get Order by ID	All fields identical to endpoint #1

ID.

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:Responses:

• 400 BAD_REQUEST:Bad Request: Access denied -— user is not buyer or seller of this order
• 401 UNAUTHORIZED:Unauthorized: MissingAuthentication or invalid authentication tokenrequired
• 404 NOT_FOUND:Not Found: Order with specified order number does not existfound

---

3. Get My Orders (Customer)

Purpose: Retrieve all orders for the authenticated customer.

Endpoint: GET {base_url}base}/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": [ {...array "orderId":of "550e8400-e29b-41d4-a716-446655440000",order "orderNumber":objects "ORD-2025-12345",(same "buyer":structure {as "accountId":endpoint "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
    }1)... ]
}

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:Responses:

• 401 UNAUTHORIZED:Unauthorized: MissingAuthentication or invalid authentication tokenrequired
• 404 NOT_FOUND: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}base}/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

SuccessResponse: 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(same matchingstructure status,as orderedendpoint by orderedAt descending

1).

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:Responses:

• 400 BAD_REQUEST:Bad Request: Invalid status value provided
• 401 UNAUTHORIZED:Unauthorized: MissingAuthentication or invalid authentication tokenrequired
• 404 NOT_FOUND:Not Found: User account not found

---

5. Get My Orders with Pagination (Customer)Paginated)

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

Endpoint: GET {base_url}base}/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	DescriptionDefault	Validation	DefaultDescription
page	integer	No	1	Page number (1-based)	Must be >= 1	1
size	integer	No	10	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": [ {"...order objects (same structure as endpoint 1)..."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:Responses:

• 400401 BAD_REQUEST:Unauthorized: InvalidAuthentication page or size parametersrequired
• 401 UNAUTHORIZED: Missing or invalid authentication token
• 404 NOT_FOUND:Not Found: User account not found

---

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

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

Endpoint: GET {base_url}base}/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	DescriptionDefault	Validation	DefaultDescription
page	integer	No	1	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

ErrorResponse: ResponseSame JSONpaginated Sample:structure as endpoint 5.

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

• 400 BAD_REQUEST:Bad Request: Invalid status value or pagination parameters
• 401 UNAUTHORIZED:Unauthorized: MissingAuthentication or invalid authentication tokenrequired
• 404 NOT_FOUND:Not Found: User account not found

---

7. Get Shop Orders (Non-Paginated)

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

Endpoint: GET {base_url}base}/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

SuccessResponse: 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(same thestructure shop,as orderedendpoint by orderedAt descending

1).

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:Responses:

• 400 BAD_REQUEST:Bad Request: User is not the owner of the specifiedthis shop
• 401 UNAUTHORIZED:Unauthorized: MissingAuthentication or invalid authentication tokenrequired
• 404 NOT_FOUND: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}base}/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

SuccessResponse: 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(same statusstructure foras theendpoint shop, ordered by orderedAt descending

1).

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:Responses:

• 400 BAD_REQUEST:Bad Request: Invalid status value or user is not shop owner
• 401 UNAUTHORIZED:Unauthorized: MissingAuthentication or invalid authentication tokenrequired
• 404 NOT_FOUND:Not Found: Shop not found or has been deleted

---

9. Get Shop Orders with Pagination(Paginated)

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

Endpoint: GET {base_url}base}/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	DescriptionDefault	Validation	DefaultDescription
page	integer	No	1	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

Response: Same paginated structure as endpoint 5.

Error Response JSON Sample:Responses:

{400 "success"Bad Request: false,User "httpStatus": "BAD_REQUEST",
  "message": "Access denied. You areis 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:Unauthorized: MissingAuthentication or invalid authentication tokenrequired
• 404 NOT_FOUND:Not Found: Shop not found or has been deleted

---

10. Get Shop Orders by Status with Pagination(Paginated)

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

Endpoint: GET {base_url}base}/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	DescriptionDefault	Validation	DefaultDescription
page	integer	No	1	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

ErrorResponse: ResponseSame JSONpaginated Sample:structure as endpoint 5.

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

• 400 BAD_REQUEST:Bad Request: Invalid status value, pagination parameters,value or user is not shop owner
• 401 UNAUTHORIZED:Unauthorized: MissingAuthentication or invalid authentication tokenrequired
• 404 NOT_FOUND:Not Found: Shop not found or has been deleted

---

11. Mark Order as Shipped (Seller Action)

Purpose: AllowsSeller seller to markmarks an order as shipped,shipped. generatesGenerates a delivery confirmation code,code and sends notificationit to the buyer.

Endpoint: POST {base_url}base}/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:Responses:

• 400 BAD_REQUEST:Bad Request: Order status is not PENDING_SHIPMENT, or user is not the seller, or confirmation code generation failedseller
• 401 UNAUTHORIZED:Unauthorized: MissingAuthentication or invalid authentication tokenrequired
• 404 NOT_FOUND:Not Found: Order not found

---

12. Confirm Delivery (Customer Action)

Purpose: AllowsCustomer customer to confirmconfirms order delivery using the 6-digit confirmation code,code. releasesReleases escrow to seller.

Endpoint: POST {base_url}base}/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 informationinfo 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 delivery confirmation code sent to customer	Must be exactlyExactly 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!"
}

SuccessNote: This response is returned directly without the standard success envelope.

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:Responses:

• 400 BAD_REQUEST:Bad Request: Invalid confirmation code, order status is not SHIPPED, user is not the buyer, maximummax attempts exceeded, code expired, no escrow found, or escrow already released
• 401 UNAUTHORIZED:Unauthorized: MissingAuthentication or invalid authentication tokenrequired
• 404 NOT_FOUND:Not Found: Order not found or no active confirmation code exists
• 422 UNPROCESSABLE_ENTITY:Unprocessable ValidationEntity: error on confirmationConfirmation code format invalid

---

13. Regenerate Confirmation Code (Customer Action)

Purpose: AllowsCustomer customer to requestrequests a new delivery confirmation code if the previous codeone was lost or expired.

Endpoint: POST {base_url}base}/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)email)
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:Responses:

• 400 BAD_REQUEST:Bad Request: Order status is not SHIPPED, user is not the buyer, or delivery already confirmed
• 401 UNAUTHORIZED:Unauthorized: MissingAuthentication or invalid authentication tokenrequired
• 404 NOT_FOUND:Not Found: Order not found

---

Quick

14. ReferenceGet Guide

Digital

HTTPDownload Method Badge Code TemplatesURL

Purpose: Generates a presigned download URL for a digital file linked to an order. The URL expires in 5 minutes.

Endpoint: GET Badge:{base}/{orderId}/downloads/{fileId}

Access Level: 🔒 Protected (Buyer only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description
orderId	UUID	Yes	Unique identifier of the order
fileId	UUID	Yes	Unique identifier of the digital file

Response JSON Sample:

<span{
  style="background-color:success": #28a745;true,
  color:"message": white;"Download padding:URL 4pxgenerated 8px;— border-radius:link 4px;expires font-family:in monospace;5 font-size:minutes",
  12px;"data": font-weight:{
    bold;">GET<fileId": "abc12345-def6-7890-ghij-klmnopqrstuv",
    "fileName": "course-material.pdf",
    "downloadUrl": "https:/span>/storage.example.com/files/...",
    "expiresAt": "2025-10-25T10:35:45",
    "downloadsRemaining": 3,
    "downloadCount": 2
  }
}

POSTResponse Badge:Fields:

<spanstyle="background-color:#007bff;color:white;padding:4px8px;border-radius:4px;font-family:
























Field
Description




fileId
Unique monospace;identifier font-size:of 12px;the font-weight:digital bold;">POST</span>file
fileName
Name of the file
downloadUrl
Presigned URL for downloading the file (expires in 5 minutes)
expiresAt
Timestamp when the download URL expires
downloadsRemaining
Number of downloads remaining for this buyer
downloadCount
Number of times this file has been downloaded
PUTError Badge:Responses:

<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:Unauthorized: Authentication required/failed (missing, invalid, expired, or malformed token)

403 Forbidden: Insufficient permissions, access denied, verification required
404 Not Found:Found: ResourceOrder or file not found
422 Unprocessable Entity:Entity: Validation errors

429 Too Many Requests: RateDownload limit exceeded
 
500or Internalaccess Servernot Error: Server errorpermitted


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