Skip to main content

Order Management

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

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

Short Description: The Order Management API enables users to manage e-commerce orders, including retrieving order details, canceling orders, marking orders as shipped, confirming deliveries, and regenerating confirmation codes. It is designed for authenticated buyers and shop owners to interact with order-related operations securely.

Hints:

  • All endpoints require Bearer Token authentication (Authorization: Bearer your_token).
  • Responses use UTC timestamps in ISO 8601 format (e.g., 2025-10-18T11:32:00Z).
  • Rate limiting: 100 requests per minute per user.
  • Ensure all monetary values are in Tanzanian Shillings (TZS) unless specified otherwise.
  • Use the sandbox environment at https://sandbox.nextgate.com/api/v1 for testing.

Standard Response Format

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

Success Response Structure

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

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-10-18T11:32:00Z",
  "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

  • 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: Retrieves detailed information about a specific order by its unique ID.

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

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

Authentication: Bearer Token

Request Headers:

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

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-18T11:32:00Z",
  "data": {
    "orderId": "123e4567-e89b-12d3-a456-426614174000",
    "orderNumber": "ORD-2025-12345",
    "buyer": {
      "accountId": "223e4567-e89b-12d3-a456-426614174001",
      "userName": "john_doe",
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    "seller": {
      "shopId": "323e4567-e89b-12d3-a456-426614174002",
      "shopName": "Example Shop",
      "shopLogo": "https://example.com/logo.png",
      "shopSlug": "example-shop"
    },
    "orderStatus": "SHIPPED",
    "deliveryStatus": "IN_TRANSIT",
    "orderSource": "DIRECT_PURCHASE",
    "items": [
      {
        "orderItemId": "423e4567-e89b-12d3-a456-426614174003",
        "productId": "523e4567-e89b-12d3-a456-426614174004",
        "productName": "Sample Product",
        "productSlug": "sample-product",
        "productImage": "https://example.com/product.jpg",
        "quantity": 2,
        "unitPrice": "5000.00",
        "subtotal": "10000.00",
        "tax": "1800.00",
        "total": "11800.00"
      }
    ],
    "subtotal": "10000.00",
    "shippingFee": "500.00",
    "tax": "1800.00",
    "totalAmount": "12300.00",
    "platformFee": "300.00",
    "sellerAmount": "12000.00",
    "currency": "TZS",
    "paymentMethod": "CARD",
    "amountPaid": "12300.00",
    "amountRemaining": "0.00",
    "deliveryAddress": "123 Main St, Dar es Salaam",
    "trackingNumber": "TRK123456789",
    "carrier": "DHL",
    "isDeliveryConfirmed": false,
    "deliveryConfirmedAt": null,
    "orderedAt": "2025-10-17T10:00:00Z",
    "shippedAt": "2025-10-17T15:00:00Z",
    "deliveredAt": null,
    "cancelledAt": null,
    "cancellationReason": null
  }
}

Success Response Fields:

Field Description
orderId 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 of order items 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 by the buyer
amountRemaining Remaining amount to be paid
deliveryAddress Address for delivery
trackingNumber Tracking number for shipment
carrier Shipping carrier (e.g., 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

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Order not found",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "Order not found"
}

Standard Error Types:

  • 400 BAD_REQUEST: Invalid order ID format
  • 401 UNAUTHORIZED: Invalid or expired token
  • 403 FORBIDDEN: User is not the buyer or shop owner
  • 404 NOT_FOUND: Order does not exist

2. Get Order by Number

Purpose: Retrieves detailed information about a specific order by its order number.

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

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

Authentication: Bearer Token

Request Headers:

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

Path Parameters:

Parameter Type Required Description Validation
orderNumber string Yes Unique order number (e.g., ORD-2025-12345) Max 50 characters, format ORD-YYYY-NNNNN

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Order retrieved successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": {
    "orderId": "123e4567-e89b-12d3-a456-426614174000",
    "orderNumber": "ORD-2025-12345",
    "buyer": {
      "accountId": "223e4567-e89b-12d3-a456-426614174001",
      "userName": "john_doe",
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    "seller": {
      "shopId": "323e4567-e89b-12d3-a456-426614174002",
      "shopName": "Example Shop",
      "shopLogo": "https://example.com/logo.png",
      "shopSlug": "example-shop"
    },
    "orderStatus": "SHIPPED",
    "deliveryStatus": "IN_TRANSIT",
    "orderSource": "DIRECT_PURCHASE",
    "items": [
      {
        "orderItemId": "423e4567-e89b-12d3-a456-426614174003",
        "productId": "523e4567-e89b-12d3-a456-426614174004",
        "productName": "Sample Product",
        "productSlug": "sample-product",
        "productImage": "https://example.com/product.jpg",
        "quantity": 2,
        "unitPrice": "5000.00",
        "subtotal": "10000.00",
        "tax": "1800.00",
        "total": "11800.00"
      }
    ],
    "subtotal": "10000.00",
    "shippingFee": "500.00",
    "tax": "1800.00",
    "totalAmount": "12300.00",
    "platformFee": "300.00",
    "sellerAmount": "12000.00",
    "currency": "TZS",
    "paymentMethod": "CARD",
    "amountPaid": "12300.00",
    "amountRemaining": "0.00",
    "deliveryAddress": "123 Main St, Dar es Salaam",
    "trackingNumber": "TRK123456789",
    "carrier": "DHL",
    "isDeliveryConfirmed": false,
    "deliveryConfirmedAt": null,
    "orderedAt": "2025-10-17T10:00:00Z",
    "shippedAt": "2025-10-17T15:00:00Z",
    "deliveredAt": null,
    "cancelledAt": null,
    "cancellationReason": null
  }
}

Success Response Fields:

Field Description
orderId 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 of order items 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 by the buyer
amountRemaining Remaining amount to be paid
deliveryAddress Address for delivery
trackingNumber Tracking number for shipment
carrier Shipping carrier (e.g., 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

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Order not found",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "Order not found"
}

Standard Error Types:

  • 400 BAD_REQUEST: Invalid order number format
  • 401 UNAUTHORIZED: Invalid or expired token
  • 403 FORBIDDEN: User is not the buyer or shop owner
  • 404 NOT_FOUND: Order does not exist

3. Get My Orders

Purpose: Retrieves a list of orders placed by the authenticated buyer.

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

Access Level: 🔒 Protected (Buyer only)

Authentication: Bearer Token

Request Headers:

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

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Orders retrieved successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": [
    {
      "orderId": "123e4567-e89b-12d3-a456-426614174000",
      "orderNumber": "ORD-2025-12345",
      "buyer": {
        "accountId": "223e4567-e89b-12d3-a456-426614174001",
        "userName": "john_doe",
        "email": "john@example.com",
        "firstName": "John",
        "lastName": "Doe"
      },
      "seller": {
        "shopId": "323e4567-e89b-12d3-a456-426614174002",
        "shopName": "Example Shop",
        "shopLogo": "https://example.com/logo.png",
        "shopSlug": "example-shop"
      },
      "orderStatus": "SHIPPED",
      "deliveryStatus": "IN_TRANSIT",
      "orderSource": "DIRECT_PURCHASE",
      "items": [
        {
          "orderItemId": "423e4567-e89b-12d3-a456-426614174003",
          "productId": "523e4567-e89b-12d3-a456-426614174004",
          "productName": "Sample Product",
          "productSlug": "sample-product",
          "productImage": "https://example.com/product.jpg",
          "quantity": 2,
          "unitPrice": "5000.00",
          "subtotal": "10000.00",
          "tax": "1800.00",
          "total": "11800.00"
        }
      ],
      "subtotal": "10000.00",
      "shippingFee": "500.00",
      "tax": "1800.00",
      "totalAmount": "12300.00",
      "platformFee": "300.00",
      "sellerAmount": "12000.00",
      "currency": "TZS",
      "paymentMethod": "CARD",
      "amountPaid": "12300.00",
      "amountRemaining": "0.00",
      "deliveryAddress": "123 Main St, Dar es Salaam",
      "trackingNumber": "TRK123456789",
      "carrier": "DHL",
      "isDeliveryConfirmed": false,
      "deliveryConfirmedAt": null,
      "orderedAt": "2025-10-17T10:00:00Z",
      "shippedAt": "2025-10-17T15:00:00Z",
      "deliveredAt": null,
      "cancelledAt": null,
      "cancellationReason": null
    }
  ]
}

Success Response Fields:

Field Description
data Array of orders, each containing the same fields as the Get Order by ID response

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "No orders found for user",
  "action_time": "2025-10-18T11:32:00Z",
  "data": "No orders found for user"
}

Standard Error Types:

  • 401 UNAUTHORIZED: Invalid or expired token
  • 404 NOT_FOUND: No orders found for the authenticated user

4. Get Shop Orders

Purpose: Retrieves a list of orders for a specific shop, accessible only by the shop owner.

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 (Bearer your_token)

Path Parameters:

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

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop orders retrieved successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": [
    {
      "orderId": "123e4567-e89b-12d3-a456-426614174000",
      "orderNumber": "ORD-2025-12345",
      "buyer": {
        "accountId": "223e4567-e89b-12d3-a456-426614174001",
        "userName": "john_doe",
        "email": "john@example.com",
        "firstName": "John",
        "lastName": "Doe"
      },
      "seller": {
        "shopId": "323e4567-e89b-12d3-a456-426614174002",
        "shopName": "Example Shop",
        "shopLogo": "https://example.com/logo.png",
        "shopSlug": "example-shop"
      },
      "orderStatus": "SHIPPED",
      "deliveryStatus": "IN_TRANSIT",
      "orderSource": "DIRECT_PURCHASE",
      "items": [
        {
          "orderItemId": "423e4567-e89b-12d3-a456-426614174003",
          "productId": "523e4567-e89b-12d3-a456-426614174004",
          "productName": "Sample Product",
          "productSlug": "sample-product",
          "productImage": "https://example.com/product.jpg",
          "quantity": 2,
          "unitPrice": "5000.00",
          "subtotal": "10000.00",
          "tax": "1800.00",
          "total": "11800.00"
        }
      ],
      "subtotal": "10000.00",
      "shippingFee": "500.00",
      "tax": "1800.00",
      "totalAmount": "12300.00",
      "platformFee": "300.00",
      "sellerAmount": "12000.00",
      "currency": "TZS",
      "paymentMethod": "CARD",
      "amountPaid": "12300.00",
      "amountRemaining": "0.00",
      "deliveryAddress": "123 Main St, Dar es Salaam",
      "trackingNumber": "TRK123456789",
      "carrier": "DHL",
      "isDeliveryConfirmed": false,
      "deliveryConfirmedAt": null,
      "orderedAt": "2025-10-17T10:00:00Z",
      "shippedAt": "2025-10-17T15:00:00Z",
      "deliveredAt": null,
      "cancelledAt": null,
      "cancellationReason": null
    }
  ]
}

Success Response Fields:

Field Description
data Array of orders, each containing the same fields as the Get Order by ID response

Error Response JSON Sample:

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

Standard Error Types:

  • 400 BAD_REQUEST: Invalid shop ID format
  • 401 UNAUTHORIZED: Invalid or expired token
  • 403 FORBIDDEN: User is not the shop owner
  • 404 NOT_FOUND: Shop does not exist or no orders found

5. Get Shop Orders by Status

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

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

Access Level: 🔒 Protected (Shop Owner only)

Authentication: Bearer Token

Request Headers:

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

Path Parameters:

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

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop orders retrieved successfully",
  "action_time": "2025-10-18T11:32:00Z",
  "data": [
    {
      "orderId": "123e4567-e89b-12d3-a456-426614174000",
      "orderNumber": "ORD-2025-12345",
      "buyer": {
        "accountId": "223e4567-e89b-12d3-a456-426614174001",
        "userName": "john_doe",
        "email": "john@example.com",
        "firstName": "John",
        "lastName": "Doe"
      },
      "seller": {
        "shopId": "323e4567-e89b-12d3-a456-426614174002",
        "shopName": "Example Shop",
        "shopLogo": "https://example.com/logo.png",
        "shopSlug": "example-shop"
      },
      "orderStatus": "SHIPPED",
      "deliveryStatus": "IN_TRANSIT",
      "orderSource": "DIRECT_PURCHASE",
      "items": [
        {
          "orderItemId": "423e4567-e89b-12d3-a456-426614174003",
          "productId": "523e4567-e89b-12d3-a456-426614174004",
          "productName": "Sample Product",
          "productSlug": "sample-product",
          "productImage": "https://example.com/product.jpg",
          "quantity": 2,
          "unitPrice": "5000.00",
          "subtotal": "10000.00",
          "tax": "1800.00",
          "total": "11800.00"
        }
      ],
      "subtotal": "10000.00",
      "shippingFee": "500.00",
      "tax": "1800.00",
      "totalAmount": "12300.00",
      "platformFee": "300.00",
      "sellerAmount": "12000.00",
      "currency": "TZS",
      "paymentMethod": "CARD",
      "amountPaid": "12300.00",
      "amountRemaining": "0.00",
      "deliveryAddress": "123 Main St, Dar es Salaam",
      "trackingNumber": "TRK123456789",
      "carrier": "DHL",
      "isDeliveryConfirmed": false,
      "deliveryConfirmedAt": null,
      "orderedAt": "2025-10-17T10:00:00Z",
      "shippedAt": "2025-10-17T15:00:00Z",
      "deliveredAt": null,
      "cancelledAt": null,
      "cancellationReason": null
    }
  ]
}

Success Response Fields:

Field Description
data Array of orders, each containing the same fields as the Get Order by ID response

Error Response JSON Sample:

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

Standard Error Types:

  • 400 BAD_REQUEST: Invalid shop ID or status format
  • 401 UNAUTHORIZED: Invalid or expired token
  • 403 FORBIDDEN: User is not the shop owner
  • 404 NOT_FOUND: Shop does not exist or no orders found for the status

Quick Reference Guide

HTTP Method Badge Code Templates

GET Badge:

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

POST Badge:

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

PUT Badge:

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

PATCH Badge:

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

DELETE Badge:

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

Common HTTP Status Codes

  • 200 OK: Successful GET/PUT/PATCH request
  • 201 Created: Successful POST request
  • 204 No Content: Successful DELETE request
  • 400 Bad Request: Invalid request data
  • 401 Unauthorized: Authentication required/failed
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 422 Unprocessable Entity: Validation errors
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error

Authentication Types

  • Bearer Token: Include Authorization: Bearer your_token in headers

Data Format Standards

  • Dates: Use ISO 8601 format (2025-10-18T11:32:00Z)
  • Currency: Tanzanian Shillings (TZS)
  • IDs: UUID format
  • Pagination: Not implemented in these endpoints
Back to top