Order Management

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

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

Short Description:

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

The Order Management API ~~enables~~handles ~~users~~the tocomplete ~~manage~~order lifecycle for the NextGate e-commerce ~~orders,~~platform. ~~including~~It ~~retrieving~~supports multiple purchase types (direct purchase, cart purchase, installment plans, and group purchases), order ~~details,~~tracking, ~~canceling~~shipping ~~orders, marking orders as shipped, confirming deliveries,~~management, and ~~regenerating~~secure delivery confirmation ~~codes. It is designed for authenticated buyers and shop owners to interact~~ with ~~order-related~~escrow ~~operations securely.~~integration.

Hints:

Authentication Required: All endpoints require Bearer ~~Token~~token authentication (Authorization: Bearer your_token).

~~Responses use UTC timestamps in ISO 8601 format (e.g.,~~ 2025-10-18T11:32:00Z).

Rate ~~limiting:~~Limiting: 100 requests per minute per ~~user.~~user

~~Ensure~~Order ~~all~~Sources: ~~monetary~~Supports ~~values~~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 ~~Tanzanian~~ISO ~~Shillings~~8601 format (~~TZS) unless specified otherwise.~~UTC)

~~Use~~Currency: ~~the~~All ~~sandbox~~amounts ~~environment~~are atin https://sandbox.nextgate.com/api/v1TZS ~~for~~(Tanzanian ~~testing.~~Shilling) with 2 decimal precision

Standard Response Format

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

Success Response Structure

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

Error Response Structure

{ "success": false, "httpStatus": "BAD_REQUEST", "message": "Error description", "action_time": "2025-10-18T11:32:00Z"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~~ - GET - Green (Safe, read-only operations)

~~POST~~ - POST - Blue (Create new resources)
~~PUT~~ - PUT - Yellow (Update/replace entire resource)
~~PATCH~~ - PATCH - Orange (Partial updates)
~~DELETE~~ - DELETE - Red (Remove resources)

Endpoints

1. Get Order by ID

~~Purpose~~Purpose:: ~~Retrieves~~Retrieve detailed information about a specific order byusing its ~~unique ID.~~UUID.

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

Access ~~Level~~Level:: 🔒 Protected (Buyer or ~~Shop~~Seller ~~Owner of the order)~~only)

~~Authentication~~Authentication:: Bearer Token

Request ~~Headers~~Headers::

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token for authentication (`Bearer your_token`)

Path ~~Parameters~~Parameters::

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

Success Response JSON ~~Sample~~Sample::

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

Success Response ~~Fields~~Fields::

Field	Description
`orderId`	Unique identifier of the order
`orderNumber`	~~Unique~~Human-readable order number (~~e.g.,~~format: ORD-~~2025-12345)~~YYYY-XXXXX)
`buyer`	~~Details~~Object ~~of the~~containing buyer ~~(accountId,~~account ~~userName, email, firstName, lastName)~~information
`seller`	~~Details~~Object ofcontaining ~~the~~ shop/seller ~~(shopId, shopName, shopLogo, shopSlug)~~information
`orderStatus`	Current status ~~of the order~~ (~~e.g.,~~PENDING_PAYMENT, PENDING_SHIPMENT, ~~SHIPPED)~~SHIPPED, DELIVERED, COMPLETED, CANCELLED, REFUNDED)
`deliveryStatus`	Delivery tracking status (~~e.g.,~~ PENDING, ~~IN_TRANSIT)~~SHIPPED, IN_TRANSIT, DELIVERED, CONFIRMED)
`orderSource`	~~Source~~Purchase ~~of the order~~type (~~e.g.,~~ DIRECT_PURCHASE, ~~INSTALLMENT)~~CART_PURCHASE, INSTALLMENT, GROUP_PURCHASE)
`items`	~~List~~Array of order items with product details
`subtotal`	~~Total cost~~Sum of ~~items~~all item totals before ~~tax~~shipping and ~~shipping~~tax
`shippingFee`	~~Cost~~Shipping ~~of shipping~~cost
`tax`	Tax amount
`totalAmount`	~~Total order~~Final amount ~~including~~(subtotal ~~tax and~~+ shipping + tax)
`platformFee`	Platform ~~fee~~commission ~~charged~~(5% of total)
`sellerAmount`	Amount ~~payable~~seller toreceives ~~the~~after ~~seller~~platform fee
`currency`	Currency ~~of the transaction~~code (~~e.g.,~~ TZS)
`paymentMethod`isDeliveryConfirmed	~~Payment method used (e.g., CARD)~~
`amountPaid`	~~Amount paid by the~~Whether buyer
`amountRemaining`	~~Remaining amount to be paid~~
`deliveryAddress`	~~Address for~~confirmed delivery
`trackingNumber`	~~Tracking~~Shipping tracking number ~~for shipment~~
`carrier`orderedAt	~~Shipping~~Order ~~carrier~~creation ~~(e.g., DHL)~~timestamp
`isDeliveryConfirmed`shippedAt	~~Whether~~Shipping ~~delivery is confirmed by the buyer~~timestamp
`deliveryConfirmedAt`deliveredAt	~~Timestamp~~Delivery ~~of delivery confirmation~~
`orderedAt`	~~Timestamp when order was placed~~
`shippedAt`	~~Timestamp when order was shipped~~
`deliveredAt`	~~Timestamp when order was delivered~~
`cancelledAt`	~~Timestamp when order was cancelled~~
`cancellationReason`	~~Reason for cancellation, if applicable~~timestamp

Error Response JSON ~~Sample~~Sample::

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

Standard Error ~~Types~~Types::

400 BAD_REQUEST:BAD_REQUEST: ~~Invalid~~Access denied - user is not buyer or seller of this order ~~ID format~~
401 UNAUTHORIZED:UNAUTHORIZED: ~~Invalid~~Missing or ~~expired~~invalid authentication token
403 FORBIDDEN~~: User is not the buyer or shop owner~~

404 NOT_FOUND:NOT_FOUND: Order does not exist

2. Get Order by Order Number

~~Purpose~~Purpose:: ~~Retrieves detailed information about a specific~~Retrieve order bydetails ~~its~~using the human-readable order number.

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

Access ~~Level~~Level:: 🔒 Protected (Buyer or ~~Shop~~Seller ~~Owner of the order)~~only)

~~Authentication~~Authentication:: Bearer Token

Request ~~Headers~~Headers::

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token for authentication (`Bearer your_token`)

Path ~~Parameters~~Parameters::

Parameter	Type	Required	Description	Validation
`orderNumber`	string	Yes	~~Unique~~Human-readable order number ~~(e.g., ORD-2025-12345)~~	~~Max 50 characters, format~~Format: ORD-YYYY-~~NNNNN~~XXXXX

Success Response JSON ~~Sample~~Sample::

{
  "success": true,
  "httpStatus": "OK",
  "message": "Order retrieved successfully",
  "action_time": "2025-10-18T11:32:00Z"25T10:30:45",
  "data": {
    "orderId": "123e4567-e89b-12d3-a456-426614174000"550e8400-e29b-41d4-a716-446655440000",
    "orderNumber": "ORD-2025-12345",
    "buyer": {
      "accountId": "223e4567-123e4567-e89b-12d3-a456-426614174001"426614174000",
      "userName": "john_doe"johndoe",
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    "seller": {
      "shopId": "323e4567-e89b-12d3-a456-426614174002"789e0123-e45b-67d8-a901-234567890abc",
      "shopName": "Example Shop"TechStore",
      "shopLogo": "https://example.cdn.nextgate.com/logo.shops/techstore.png",
      "shopSlug": "example-shop"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": "423e4567-e89b-12d3-a456-426614174003"111e2222-e33b-44d5-a666-777788889999",
          "productId": "523e4567-e89b-12d3-a456-426614174004"abc12345-def6-7890-ghij-klmnopqrstuv",
          "productName": "SampleWireless Product"Headphones",
          "productSlug": "sample-product"wireless-headphones",
          "productImage": "https://example.cdn.nextgate.com/product.products/headphones.jpg",
          "quantity": 2,
          "unitPrice": "5000.00",85000.00,
          "subtotal": "10000.00",170000.00,
          "tax": "1800.00",0.00,
          "total": "11800.00"170000.00
        }
      ],
      "subtotal": "10000.00",170000.00,
      "shippingFee": "500.00",5000.00,
      "tax": "1800.00",0.00,
      "totalAmount": "12300.00",175000.00,
      "platformFee": "300.00",8750.00,
      "sellerAmount": "12000.00",166250.00,
      "currency": "TZS",
      "paymentMethod": "CARD"MPESA",
      "amountPaid": "12300.00",175000.00,
      "amountRemaining": "0.00",00,
      "deliveryAddress": "123 Main St, Dar es Salaam"Salaam, Tanzania",
      "trackingNumber": "TRK123456789"TRACK-550E8400",
      "carrier": "DHL"NextGate Shipping",
      "isDeliveryConfirmed": false,
      "deliveryConfirmedAt": null,
      "orderedAt": "2025-10-17T10:00:00Z"20T14:30:00",
      "shippedAt": "2025-10-17T15:00:00Z"21T09:15:00",
      "deliveredAt": null,
      "cancelledAt": null,
      "cancellationReason": null
    }
  ]
}

Success Response ~~Fields~~Fields::

Field	Description
`orderId`data	~~Unique identifier of the order~~
`orderNumber`	~~Unique order number (e.g., ORD-2025-12345)~~
`buyer`	~~Details of the buyer (accountId, userName, email, firstName, lastName)~~
`seller`	~~Details of the seller (shopId, shopName, shopLogo, shopSlug)~~
`orderStatus`	~~Current status of the order (e.g., PENDING_SHIPMENT, SHIPPED)~~
`deliveryStatus`	~~Delivery status (e.g., PENDING, IN_TRANSIT)~~
`orderSource`	~~Source of the order (e.g., DIRECT_PURCHASE, INSTALLMENT)~~
`items`	~~List~~Array of order ~~items~~objects, ~~with product details~~
`subtotal`	~~Total cost of items before tax and shipping~~
`shippingFee`	~~Cost of shipping~~
`tax`	~~Tax amount~~
`totalAmount`	~~Total order amount including tax and shipping~~
`platformFee`	~~Platform fee charged~~
`sellerAmount`	~~Amount payable to the seller~~
`currency`	~~Currency of the transaction (e.g., TZS)~~
`paymentMethod`	~~Payment method used (e.g., CARD)~~
`amountPaid`	~~Amount paid~~ordered by ~~the~~orderedAt ~~buyer~~
`amountRemaining`	~~Remaining amount to be paid~~
`deliveryAddress`	~~Address for delivery~~
`trackingNumber`	~~Tracking number for shipment~~
`carrier`	~~Shipping carrier~~descending (~~e.g.,~~newest ~~DHL)~~
`isDeliveryConfirmed`	~~Whether delivery is confirmed by the buyer~~
`deliveryConfirmedAt`	~~Timestamp of delivery confirmation~~
`orderedAt`	~~Timestamp when order was placed~~
`shippedAt`	~~Timestamp when order was shipped~~
`deliveredAt`	~~Timestamp when order was delivered~~
`cancelledAt`	~~Timestamp when order was cancelled~~
`cancellationReason`	~~Reason for cancellation, if applicable~~first)

Error Response JSON ~~Sample~~Sample::

{
  "success": false,
  "httpStatus": "NOT_FOUND"UNAUTHORIZED",
  "message": "OrderUser not found"authenticated",
  "action_time": "2025-10-18T11:32:00Z"25T10:30:45",
  "data": "OrderUser not found"authenticated"
}

Standard Error ~~Types~~Types::

400 BAD_REQUEST~~: Invalid order number format~~

401 UNAUTHORIZED:UNAUTHORIZED: ~~Invalid~~Missing or ~~expired~~invalid authentication token
403404 FORBIDDEN:NOT_FOUND: User isaccount not ~~the buyer or shop owner~~

404 NOT_FOUND~~: Order does not exist~~found

3.

4. Get My Orders

by Status (Customer)

~~Purpose~~Purpose:: ~~Retrieves~~Retrieve ~~a list of~~customer orders ~~placed~~filtered by ~~the~~specific ~~authenticated~~order ~~buyer.~~status.

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

Access ~~Level~~Level:: 🔒 Protected (~~Buyer~~Customer only)

~~Authentication~~Authentication:: Bearer Token

Request ~~Headers~~Headers::

(Beareryour_token)

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~~Sample::

{
  "success": true,
  "httpStatus": "OK",
  "message": "Orders retrieved successfully",
  "action_time": "2025-10-18T11:32:00Z"25T10:30:45",
  "data": [
    {
      "orderId": "123e4567-e89b-12d3-a456-426614174000"550e8400-e29b-41d4-a716-446655440000",
      "orderNumber": "ORD-2025-12345",
      "buyer": {
        "accountId": "223e4567-123e4567-e89b-12d3-a456-426614174001"426614174000",
        "userName": "john_doe"johndoe",
        "email": "john@example.com",
        "firstName": "John",
        "lastName": "Doe"
      },
      "seller": {
        "shopId": "323e4567-e89b-12d3-a456-426614174002"789e0123-e45b-67d8-a901-234567890abc",
        "shopName": "Example Shop"TechStore",
        "shopLogo": "https://example.cdn.nextgate.com/logo.shops/techstore.png",
        "shopSlug": "example-shop"techstore"
      },
      "orderStatus": "SHIPPED",
      "deliveryStatus": "IN_TRANSIT",
      "orderSource": "DIRECT_PURCHASE"CART_PURCHASE",
      "items": [
        {
          "orderItemId": "423e4567-e89b-12d3-a456-426614174003"111e2222-e33b-44d5-a666-777788889999",
          "productId": "523e4567-e89b-12d3-a456-426614174004"abc12345-def6-7890-ghij-klmnopqrstuv",
          "productName": "SampleLaptop Product"Bag",
          "productSlug": "sample-product"laptop-bag",
          "productImage": "https://example.cdn.nextgate.com/product.products/bag.jpg",
          "quantity": 2,1,
          "unitPrice": "5000.00",45000.00,
          "subtotal": "10000.00",45000.00,
          "tax": "1800.00",0.00,
          "total": "11800.00"45000.00
        }
      ],
      "subtotal": "10000.00",45000.00,
      "shippingFee": "500.00",3000.00,
      "tax": "1800.00",0.00,
      "totalAmount": "12300.00",48000.00,
      "platformFee": "300.00",2400.00,
      "sellerAmount": "12000.00",45600.00,
      "currency": "TZS",
      "paymentMethod": "CARD"AIRTEL_MONEY",
      "amountPaid": "12300.00",48000.00,
      "amountRemaining": "0.00",00,
      "deliveryAddress": "123789 MainBusiness St,Ave, DarMwanza, es Salaam"Tanzania",
      "trackingNumber": "TRK123456789"TRACK-550E8401",
      "carrier": "DHL"NextGate Shipping",
      "isDeliveryConfirmed": false,
      "deliveryConfirmedAt": null,
      "orderedAt": "2025-10-17T10:00:00Z"24T11:45:00",
      "shippedAt": "2025-10-17T15:00:00Z"25T07:30:00",
      "deliveredAt": null,
      "cancelledAt": null,
      "cancellationReason": null
    }
  ]
}

Success Response ~~Fields~~Fields::

Field	Description
`data`	Array of ~~orders,~~order ~~each~~objects ~~containing~~with ~~the~~matching ~~same~~status, ~~fields as the Get Order~~ordered by IDorderedAt ~~response~~descending

Error Response JSON ~~Sample~~Sample::

{
  "success": false,
  "httpStatus": "NOT_FOUND"BAD_REQUEST",
  "message": "NoInvalid ordersorder foundstatus: for user"INVALID_STATUS",
  "action_time": "2025-10-18T11:32:00Z"25T10:30:45",
  "data": "NoInvalid ordersorder foundstatus: for user"INVALID_STATUS"
}

Standard Error ~~Types~~Types::

401400 UNAUTHORIZED:BAD_REQUEST: Invalid status value provided

401 UNAUTHORIZED: Missing or ~~expired~~invalid authentication token
404 NOT_FOUND:NOT_FOUND: NoUser ~~orders~~account not found ~~for the authenticated user~~

4.

5. Get ShopMy Orders

with Pagination (Customer)

~~Purpose~~Purpose:: ~~Retrieves~~Retrieve ~~a list of~~customer orders with pagination support for abetter ~~specific shop, accessible only by the shop owner.~~performance.

~~Endpoint~~Endpoint:: GET {base_url}/orders/shop/{shopId}/ordersmy-orders/paged

Access ~~Level~~Level:: 🔒 Protected (~~Shop Owner~~Customer only)

~~Authentication~~Authentication:: Bearer Token

Request ~~Headers~~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 ~~your_token~~)Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path ~~Parameters~~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~~Sample::

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop ordersOrders retrieved successfully",
  "action_time": "2025-10-18T11:32:00Z"25T10:30:45",
  "data": [
    {
      "orderId": "123e4567-e89b-12d3-a456-426614174000"550e8400-e29b-41d4-a716-446655440000",
      "orderNumber": "ORD-2025-12345",
      "buyer": {
        "accountId": "223e4567-123e4567-e89b-12d3-a456-426614174001"426614174000",
        "userName": "john_doe"johndoe",
        "email": "john@example.com",
        "firstName": "John",
        "lastName": "Doe"
      },
      "seller": {
        "shopId": "323e4567-e89b-12d3-a456-426614174002"789e0123-e45b-67d8-a901-234567890abc",
        "shopName": "Example Shop"TechStore",
        "shopLogo": "https://example.cdn.nextgate.com/logo.shops/techstore.png",
        "shopSlug": "example-shop"techstore"
      },
      "orderStatus": "SHIPPED"PENDING_SHIPMENT",
      "deliveryStatus": "IN_TRANSIT"PENDING",
      "orderSource": "DIRECT_PURCHASE",
      "items": [
        {
          "orderItemId": "423e4567-e89b-12d3-a456-426614174003"111e2222-e33b-44d5-a666-777788889999",
          "productId": "523e4567-e89b-12d3-a456-426614174004"abc12345-def6-7890-ghij-klmnopqrstuv",
          "productName": "Sample Product"Keyboard",
          "productSlug": "sample-product"keyboard",
          "productImage": "https://example.cdn.nextgate.com/product.products/keyboard.jpg",
          "quantity": 2,1,
          "unitPrice": "5000.00",75000.00,
          "subtotal": "10000.00",75000.00,
          "tax": "1800.00",0.00,
          "total": "11800.00"75000.00
        }
      ],
      "subtotal": "10000.00",75000.00,
      "shippingFee": "500.00",4000.00,
      "tax": "1800.00",0.00,
      "totalAmount": "12300.00",79000.00,
      "platformFee": "300.00",3950.00,
      "sellerAmount": "12000.00",75050.00,
      "currency": "TZS",
      "paymentMethod": "CARD"TIGOPESA",
      "amountPaid": "12300.00",79000.00,
      "amountRemaining": "0.00",00,
      "deliveryAddress": "123 MainOffice St,Complex, DarMorogoro, es Salaam"Tanzania",
      "trackingNumber": "TRK123456789",null,
      "carrier": "DHL",null,
      "isDeliveryConfirmed": false,
      "deliveryConfirmedAt": null,
      "orderedAt": "2025-10-17T10:25T09:00:00Z"00",
      "shippedAt": "2025-10-17T15:00:00Z",null,
      "deliveredAt": null,
      "cancelledAt": null,
      "cancellationReason": null
    }
  ]
}

Success Response ~~Fields~~Fields::

Field	Description
`data`	Array of ~~orders,~~all ~~each~~order ~~containing~~objects for the ~~same~~shop, ~~fields as the Get Order~~ordered by IDorderedAt ~~response~~descending

Error Response JSON ~~Sample~~Sample::

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

Standard Error ~~Types~~Types::

400 BAD_REQUEST~~: Invalid shop ID format~~

401 UNAUTHORIZED~~: Invalid or expired token~~

403 FORBIDDEN:BAD_REQUEST: User is not the owner of the specified shop ~~owner~~
401 UNAUTHORIZED: Missing or invalid authentication token

404 NOT_FOUND:NOT_FOUND: Shop ~~does~~ not ~~exist~~found or nohas ~~orders~~been ~~found~~deleted

5.

8. Get Shop Orders by Status

(Non-Paginated)

~~Purpose~~Purpose:: ~~Retrieves~~Retrieve ~~a list of~~shop orders ~~for a specific shop~~ filtered by specific order ~~status, accessible only by the shop owner.~~status.

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

Access ~~Level~~Level:: 🔒 Protected (Shop Owner only)

~~Authentication~~Authentication:: Bearer Token

Request ~~Headers~~Headers::

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token for authentication (`Bearer your_token`)

Path ~~Parameters~~Parameters::

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

Success Response JSON ~~Sample~~Sample::

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop ordersOrders retrieved successfully",
  "action_time": "2025-10-18T11:32:00Z"25T10:30:45",
  "data": [
    {
      "orderId": "123e4567-e89b-12d3-a456-426614174000"550e8400-e29b-41d4-a716-446655440000",
      "orderNumber": "ORD-2025-12345",
      "buyer": {
        "accountId": "223e4567-123e4567-e89b-12d3-a456-426614174001"426614174000",
        "userName": "john_doe"johndoe",
        "email": "john@example.com",
        "firstName": "John",
        "lastName": "Doe"
      },
      "seller": {
        "shopId": "323e4567-e89b-12d3-a456-426614174002"789e0123-e45b-67d8-a901-234567890abc",
        "shopName": "Example Shop"TechStore",
        "shopLogo": "https://example.cdn.nextgate.com/logo.shops/techstore.png",
        "shopSlug": "example-shop"techstore"
      },
      "orderStatus": "SHIPPED"PENDING_SHIPMENT",
      "deliveryStatus": "IN_TRANSIT"PENDING",
      "orderSource": "DIRECT_PURCHASE"GROUP_PURCHASE",
      "items": [
        {
          "orderItemId": "423e4567-e89b-12d3-a456-426614174003"111e2222-e33b-44d5-a666-777788889999",
          "productId": "523e4567-e89b-12d3-a456-426614174004"abc12345-def6-7890-ghij-klmnopqrstuv",
          "productName": "SamplePhone Product"Case",
          "productSlug": "sample-product"phone-case",
          "productImage": "https://example.cdn.nextgate.com/product.products/case.jpg",
          "quantity": 2,1,
          "unitPrice": "5000.00",12000.00,
          "subtotal": "10000.00",12000.00,
          "tax": "1800.00",0.00,
          "total": "11800.00"12000.00
        }
      ],
      "subtotal": "10000.00",12000.00,
      "shippingFee": "500.00",2000.00,
      "tax": "1800.00",0.00,
      "totalAmount": "12300.00",14000.00,
      "platformFee": "300.00",700.00,
      "sellerAmount": "12000.00",13300.00,
      "currency": "TZS",
      "paymentMethod": "CARD"MPESA",
      "amountPaid": "12300.00",14000.00,
      "amountRemaining": "0.00",00,
      "deliveryAddress": "123999 MainGroup St,Buy DarLane, esMbeya, Salaam"Tanzania",
      "trackingNumber": "TRK123456789",null,
      "carrier": "DHL",null,
      "isDeliveryConfirmed": false,
      "deliveryConfirmedAt": null,
      "orderedAt": "2025-10-17T10:00:00Z"25T08:45:00",
      "shippedAt": "2025-10-17T15:00:00Z",null,
      "deliveredAt": null,
      "cancelledAt": null,
      "cancellationReason": null
    }
  ]
}

Success Response ~~Fields~~Fields::

Field	Description
`data`	Array of ~~orders,~~order ~~each~~objects ~~containing~~matching status for the ~~same~~shop, ~~fields as the Get Order~~ordered by IDorderedAt ~~response~~descending

Error Response JSON ~~Sample~~Sample::

{
  "success": false,
  "httpStatus": "FORBIDDEN"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-18T11:32:00Z"25T10:30:45",
  "data": "Access denied. You are not the owner of this shop"
}

Standard Error ~~Types~~Types::

400 BAD_REQUEST:BAD_REQUEST: Invalid ~~shop~~pagination IDparameters or ~~status~~user ~~format~~is not shop owner
401 UNAUTHORIZED:UNAUTHORIZED: ~~Invalid~~Missing or ~~expired~~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 403{base_url}/orders/shop/{shopId}/orders/status/{status}/paged

~~FORBIDDEN~~

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": Usertrue,
  "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 ~~shop~~seller, ~~owner~~or confirmation code generation failed
401 UNAUTHORIZED: Missing or invalid authentication token

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

Authentication Types

Bearer ~~Token~~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~~Dates:~~: Use~~ ISO 8601 format (2025-10-~~18T11:32:~~25T14:30:00Z)
- ~~Currency~~Currency:: TZS (Tanzanian ~~Shillings~~Shilling), ~~(TZS)~~amounts in decimal with 2 precision
- ~~IDs~~IDs:: UUID format
- ~~Pagination~~Pagination:: ~~Not~~1-based ~~implemented~~indexing in(page ~~these~~1 ~~endpoints~~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

Order Management

Short Description:

Hints:

Standard Response Format

Success Response Structure

Error Response Structure

Standard Response Fields

HTTP Method Badge Standards

Endpoints

1. Get Order by ID

2. Get Order by Order Number

3. Get My Orders (Customer)

3.

4. Get My Orders

4.

5. Get ShopMy Orders

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

7. Get Shop Orders (Non-Paginated)

5.

8. Get Shop Orders by Status

9. Get Shop Orders with Pagination

10. Get Shop Orders by Status with Pagination

11. Mark Order as Shipped (Seller Action)

12. Confirm Delivery (Customer Action)

13. Regenerate Confirmation Code (Customer Action)

Quick Reference Guide

HTTP Method Badge Code Templates

Common HTTP Status Codes

Authentication Types

Order Status Flow

Delivery Status Values

Order Source Types

Data Format Standards

Security Notes

Pagination Best Practices