Skip to main content

Order Management

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

Base URL: api/v1/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, order tracking, shipping management, delivery confirmation with 6-digit codes, escrow integration, and digital product downloads.

Hints:

  • All endpoints require Bearer token authentication
  • Order sources: DIRECT_PURCHASE, CART_PURCHASE, DIGITAL_PURCHASE, INSTALLMENT, GROUP_PURCHASE
  • Delivery confirmation uses a 6-digit code (SHA-256 hashed with salt, expires in 30 days, max 5 attempts)
  • Digital orders have deliveryStatus: NOT_APPLICABLE
  • Confirm-delivery response is returned directly (not wrapped in the standard response envelope)
  • Every order detail response includes a timeline array — ordered list of status steps with timestamps. Steps not yet reached have timestamp: null and isCompleted: false

Endpoints

1. Get Order by ID

Purpose: Retrieve detailed information about a specific order.

Endpoint: GET {base}/{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
orderId UUID Yes Unique identifier of the order

Response JSON Sample:

{
  "success": true,
  "message": "Order retrieved successfully",
  "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"shopLogoMedia": {
        "fileId": "9f8e7d6c-5b4a-3210-9876-543210fedcba",
        "status": "READY",
        "thumbUrl": "https://cdn.example.com/shops/techstore.techstore-thumb.webp",
        "mimeType": "image/png"
      },
      "shopSlug": "techstore"
    },
    "productOrderStatus": "SHIPPED",
    "deliveryStatus": "IN_TRANSIT",
    "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.example.com/products/headphones.jpg",
        "productType": "PHYSICAL",
        "fileIds": null,
        "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,
    "timeline": [
      {
        "status": "ORDER_PLACED",
        "label": "Order Placed",
        "timestamp": "2025-10-20T14:30:00",
        "isCompleted": true,
        "note": null
      },
      {
        "status": "SHIPPED",
        "label": "Shipped",
        "timestamp": "2025-10-21T09:15:00",
        "isCompleted": true,
        "note": "NextGate Shipping · TRACK-550E8400"
      },
      {
        "status": "DELIVERED",
        "label": "Delivered",
        "timestamp": null,
        "isCompleted": false,
        "note": null
      },
      {
        "status": "COMPLETED",
        "label": "Order Completed",
        "timestamp": null,
        "isCompleted": false,
        "note": null
      }
    ]
  }
}

Response Fields:

Field Description
orderId Unique identifier of the order
orderNumber Human-readable order number
buyer Buyer account info (accountId, userName, email, firstName, lastName)
seller Shop info (shopId, shopName, shopLogo,shopLogoMedia, shopSlug)
productOrderStatus PENDING_PAYMENT, PENDING_SHIPMENT, SHIPPED, DELIVERED, AWAITING_BUYER_CONFIRM, COMPLETED, DISPUTED, CANCELLED, REFUNDED
deliveryStatus PENDING, SHIPPED, IN_TRANSIT, DELIVERED, CONFIRMED, NOT_APPLICABLE
productOrderSource DIRECT_PURCHASE, CART_PURCHASE, DIGITAL_PURCHASE, INSTALLMENT, GROUP_PURCHASE
items Array of order items — see item fields below
items[].productType PHYSICAL or DIGITAL — frontend uses this to show tracking UI vs download UI
items[].fileIds List of file UUIDs for the item — populated only when productType is DIGITAL, null for physical. Use these with endpoint 14/1515/16 to download files
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
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). Currently always the hardcoded string "NexGate Shipping" — no real carrier integration yet. Note: this is a typo of the platform name "NextGate" baked into the code; flagged as a candidate one-line fix.
isDeliveryConfirmed Whether buyer confirmed delivery
deliveryConfirmedAt Timestamp of delivery 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)
timeline Ordered list of status steps — see Timeline Fields below
timeline[].status Step identifier: ORDER_PLACED, SHIPPED, DELIVERED, COMPLETED, FILES_AVAILABLE (digital), CANCELLED, DISPUTED, REFUNDED
timeline[].label Human-readable step label
timeline[].timestamp When this step occurred (null if not yet reached)
timeline[].isCompleted true if this step has been reached
timeline[].note Optional context — shipping carrier + tracking on SHIPPED, cancellation reason on CANCELLED, "Confirmed by buyer" or "Auto-confirmed" on COMPLETED, null otherwise

Error Responses:

  • 400 Bad Request: Access denied — user is not buyer or seller of this order
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Order not found

2. Get Order by Order Number

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

Endpoint: GET {base}/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
orderNumber string Yes Human-readable order number (e.g. ORD-2025-12345)

Response: Same structure as Get Order by ID.

Error Responses:

  • 400 Bad Request: Access denied — user is not buyer or seller of this order
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Order not found

3. Get My Orders

Purpose: Retrieve all orders for the authenticated customer.

Endpoint: GET {base}/my-orders

Access Level: 🔒 Protected (Customer only)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Response JSON Sample:

{
  "success": true,
  "message": "Orders retrieved successfully",
  "data": [ ...array of order objects (same structure as endpoint 1)... ]
}

Error Responses:

  • 401 Unauthorized: Authentication required
  • 404 Not Found: User account not found

4. Get My Orders by Status

Purpose: Retrieve customer orders filtered by order status.

Endpoint: GET {base}/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
status enum Yes PENDING_PAYMENT, PENDING_SHIPMENT, SHIPPED, DELIVERED, AWAITING_BUYER_CONFIRM, COMPLETED, DISPUTED, CANCELLED, REFUNDED

Response: Array of order objects (same structure as endpoint 1).

Error Responses:

  • 400 Bad Request: Invalid status value
  • 401 Unauthorized: Authentication required
  • 404 Not Found: User account not found

5. Get My Orders (Paginated)

Purpose: Retrieve customer orders with pagination.

Endpoint: GET {base}/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 Default Description
page integer No 1 Page number (1-based)
size integer No 10 Number of items per page

Response JSON Sample:

{
  "success": true,
  "message": "Orders retrieved successfully",
  "data": {
    "orders": [ "...order objects (same structure as endpoint 1)..." ],
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 25,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": false
  }
}

Error Responses:

  • 401 Unauthorized: Authentication required
  • 404 Not Found: User account not found

6. Get My Orders by Status (Paginated)

Purpose: Retrieve customer orders filtered by status with pagination.

Endpoint: GET {base}/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
status enum Yes PENDING_PAYMENT, PENDING_SHIPMENT, SHIPPED, DELIVERED, AWAITING_BUYER_CONFIRM, COMPLETED, DISPUTED, CANCELLED, REFUNDED

Query Parameters:

Parameter Type Required Default Description
page integer No 1 Page number (1-based)
size integer No 10 Number of items per page

Response: Same paginated structure as endpoint 5.

Error Responses:

  • 400 Bad Request: Invalid status value
  • 401 Unauthorized: Authentication required
  • 404 Not Found: User account not found

7. Get Shop Orders

Purpose: Retrieve all orders for a specific shop.

Endpoint: GET {base}/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
shopId UUID Yes Unique identifier of the shop

Response: Array of order objects (same structure as endpoint 1).

Error Responses:

  • 400 Bad Request: User is not the owner of this shop
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Shop not found

8. Get Shop Orders by Status

Purpose: Retrieve shop orders filtered by order status.

Endpoint: GET {base}/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
shopId UUID Yes Unique identifier of the shop
status enum Yes PENDING_PAYMENT, PENDING_SHIPMENT, SHIPPED, DELIVERED, AWAITING_BUYER_CONFIRM, COMPLETED, DISPUTED, CANCELLED, REFUNDED

Response: Array of order objects (same structure as endpoint 1).

Error Responses:

  • 400 Bad Request: Invalid status value or user is not shop owner
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Shop not found

9. Get Shop Orders (Paginated)

Purpose: Retrieve shop orders with pagination.

Endpoint: GET {base}/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
shopId UUID Yes Unique identifier of the shop

Query Parameters:

Parameter Type Required Default Description
page integer No 1 Page number (1-based)
size integer No 10 Number of items per page

Response: Same paginated structure as endpoint 5.

Error Responses:

  • 400 Bad Request: User is not the owner of this shop
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Shop not found

10. Get Shop Orders by Status (Paginated)

Purpose: Retrieve shop orders filtered by status with pagination.

Endpoint: GET {base}/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
shopId UUID Yes Unique identifier of the shop
status enum Yes PENDING_PAYMENT, PENDING_SHIPMENT, SHIPPED, DELIVERED, AWAITING_BUYER_CONFIRM, COMPLETED, DISPUTED, CANCELLED, REFUNDED

Query Parameters:

Parameter Type Required Default Description
page integer No 1 Page number (1-based)
size integer No 10 Number of items per page

Response: Same paginated structure as endpoint 5.

Error Responses:

  • 400 Bad Request: Invalid status value or user is not shop owner
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Shop not found

11. Mark Order as Shipped

Purpose: Seller marks an order as shipped. Generates a delivery confirmation code and sends it to the buyer.

Endpoint: POST {base}/{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
orderId UUID Yes Unique identifier of the order

Response JSON Sample:

{
  "success": true,
  "message": "Order marked as shipped",
  "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
  }
}

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

  • 400 Bad Request: Order is a digital order (does not require shipping), order status is not PENDING_SHIPMENT, or user is not the seller
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Order not found

12. Confirm Delivery

Purpose: Customer confirms order delivery using the 6-digit confirmation code. Releases escrow to seller.

Endpoint: POST {base}/{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 info 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
orderId UUID Yes Unique identifier of the order

Request JSON Sample:

{
  "confirmationCode": "123456"
}

Request Body Parameters:

Parameter Type Required Description Validation
confirmationCode string Yes 6-digit delivery confirmation code Exactly 6 digits (0-9)

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!"
}

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

  • 400 Bad Request: Order is a digital order (completeddoes automatically,not nouse delivery-confirmation needed)codes — see endpoint 14, "Confirm Digital Delivery"), invalid confirmation code, order not SHIPPED, user is not buyer, max attempts exceeded, code expired, or escrow already released
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Order not found or no active confirmation code
  • 422 Unprocessable Entity: Confirmation code format invalid

13. Regenerate Confirmation Code

Purpose: Customer requests a new delivery confirmation code if the previous one was lost or expired.

Endpoint: POST {base}/{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
orderId UUID Yes Unique identifier of the order

Response JSON Sample:

{
  "success": true,
  "message": "Confirmation code regenerated successfully",
  "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"
  }
}

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)
codeExpiresAt When the new code expires (30 days from generation)
maxAttempts Maximum number of verification attempts allowed
message Confirmation message

Error Responses:

  • 400 Bad Request: Order is a digital order (does not use delivery confirmation codes), order status is not SHIPPED, user is not the buyer, or delivery already confirmed
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Order not found

14. Confirm Digital Delivery

Purpose: Buyer confirms receipt of a digital order. Releases escrow to the seller and completes the order immediately, instead of waiting for the automatic confirmation window (see "Digital Download Flow" below). This is the digital-order equivalent of endpoint 12 ("Confirm Delivery") — physical orders use a 6-digit code, digital orders use this no-body endpoint instead.

Endpoint: POST {base}/{orderId}/confirm-digital

Access Level: 🔒 Protected (Buyer/Customer only)

Authentication: Bearer Token

Request Headers:

HeaderTypeRequiredDescription
AuthorizationstringYesBearer token for authentication

Path Parameters:

ParameterTypeRequiredDescription
orderIdUUIDYesUnique identifier of the order

Request Body: None.

Response JSON Sample:

{
  "success": true,
  "message": "Digital product confirmed. Payment released to seller.",
  "data": null
}

Error Responses:

  • 400 Bad Request: Order is not a digital order, user is not the buyer, or order is not in AWAITING_BUYER_CONFIRM status (already confirmed, still processing, or disputed)
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Order not found

15. Get Digital Download URL

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

Endpoint: GET {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:

{
  "success": true,
  "message": "Download URL generated — link expires in 5 minutes",
  "data": {
    "fileId": "abc12345-def6-7890-ghij-klmnopqrstuv",
    "fileName": "course-material.pdf",
    "downloadUrl": "https://storage.example.com/files/...",
    "expiresAt": "2025-10-25T10:35:45",
    "downloadsRemaining": 3,
    "downloadCount": 2
  }
}

Response Fields:

Field Description
fileId Unique identifier of the digital 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

Error Responses:

  • 401 Unauthorized: Authentication required
  • 404 Not Found: Order or file not found
  • 422 Unprocessable Entity: Download limit exceeded or access not permitted

15.16. List Order Downloads

Purpose: Returns all digital files the buyer has access to for a given order, including fileId needed to generate download URLs. Call this first before endpoint 14.15.

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

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

Response JSON Sample:

{
  "success": true,
  "message": "2 file(s) available for download",
  "data": [
    {
      "fileId": "f1a2b3c4-def5-6789-ghij-klmnopqrstuv",
      "fileName": "spring-boot-course.zip",
      "contentType": "application/zip",
      "fileSize": 524288000,
      "downloadCount": 1,
      "downloadsRemaining": 4,
      "accessExpiresAt": "2026-06-18T10:00:00",
      "canDownload": true
    },
    {
      "fileId": "a9b8c7d6-e5f4-3210-hijk-lmnopqrstuvw",
      "fileName": "bonus-resources.pdf",
      "contentType": "application/pdf",
      "fileSize": 2048000,
      "downloadCount": 0,
      "downloadsRemaining": 4,
      "accessExpiresAt": "2026-06-18T10:00:00",
      "canDownload": true
    }
  ]
}

Response Fields:

Field Description
fileId Use this in endpoint 1415 to get the actual download URL
fileName Display name of the file
contentType MIME type of the file
fileSize File size in bytes
downloadCount How many times this buyer has downloaded this file
downloadsRemaining Downloads left before cap is hit (null = unlimited)
accessExpiresAt When this buyer's access to this file expires
canDownload false if access is revoked, expired, or download cap reached

Error Responses:

  • 401 Unauthorized: Authentication required
  • 404 Not Found: Order not found or does not belong to this buyer
  • 422 Unprocessable Entity: Order has no digital files

Order Creation — How Orders Are Generated

Orders are never created manually. They are generated automatically when a checkout session moves to PAYMENT_COMPLETED. The system reads the session, applies grouping rules, and creates one or more orders depending on the cart contents and purchase type.

Order Grouping Rules

The grouping key is (shop + product type). Two items end up in the same order only if they share both the same shop and the same product type.

Scenario Result
Same shop, same type (both PHYSICAL) 1 order
Same shop, same type (both DIGITAL) 1 order
Same shop, different types (PHYSICAL + DIGITAL) 2 separate orders
Different shops, same type 1 order per shop
Different shops, different types 1 order per shop per type

Why split by type? Digital orders skip shipping and are downloadable immediately, then complete immediatelyvia buyer confirmation or an automatic timeout (nosee shipping,"Digital escrowDownload releasedFlow" on creation)below). Physical orders wait for seller shipment then buyer confirmation. Mixing them in one order would make status tracking and escrow management impossible.

Scenario 1 — Direct Purchase (Buy Now)

Buyer clicks Buy Now on a single product. Always produces exactly one order.

Physical product:

Buyer → Buy Now → Payment
  → 1 order created (source: DIRECT_PURCHASE)
  → status: PENDING_SHIPMENT
  → escrow held until buyer confirms delivery
  → seller ships → buyer confirms with 6-digit code → escrow released → COMPLETED

Digital product:

Buyer → Buy Now → Payment
  → 1 order created (source: DIGITAL_PURCHASE)
  → status: COMPLETED immediately
  → escrow releasedAWAITING_BUYER_CONFIRM immediately
  → DigitalDownloadAccess records created for all active files
  → buyer can download right away (escrow still held)
  → order completes + escrow releases when buyer calls
    POST {base}/{orderId}/confirm-digital, OR automatically after
    app.digital.order.auto-confirm-days (default: 3 days)

Scenario 2 — Cart Purchase

Buyer checks out a cart with multiple items. The system groups by (shop, product type) and creates one order per group.

Example cart:

Item Shop Type
Wireless Headphones TechStore PHYSICAL
Spring Boot Course (PDF) TechStore DIGITAL
Running Shoes SportShop PHYSICAL

Result: 3 orders created

Order #1 → TechStore | PHYSICAL
  source: CART_PURCHASE
  status: PENDING_SHIPMENT
  shipping: split proportionallyequally across shops (if multi-shopshop)

Order #2 → TechStore | DIGITAL
  source: DIGITAL_PURCHASE
  status: COMPLETEDAWAITING_BUYER_CONFIRM immediately
  shipping: TZS 0
  → DigitalDownloadAccess created for Spring Boot Course files
  → buyer can download immediately (escrow still held)
  → completes via POST /confirm-digital or auto-confirm after 3 days (default)

Order #3 → SportShop | PHYSICAL
  source: CART_PURCHASE
  status: PENDING_SHIPMENT
  shipping: split proportionallyequally across shops

Shipping split rule: If the cart has items from multiple shops, the total shipping cost is divided equally across the number of distinct shops.shops (not proportional to each shop's item count or value). Each physical order gets its share.

Scenario 3 — Installment Purchase (IMMEDIATE fulfillment)

Buyer pays in installments but gets the product after the first payment.

Physical product:

First payment → order created (source: INSTALLMENT)
  → status: PENDING_SHIPMENT
  → seller ships after first payment
  → buyer confirms delivery → escrow released proportionally as payments come in

Remaining payments → collected without creating new orders

Digital product:

First payment → order created (source: INSTALLMENT → detected as DIGITAL_PURCHASE)
  → status: COMPLETEDAWAITING_BUYER_CONFIRM immediately
  → DigitalDownloadAccess created
  → buyer can download after first payment (escrow still held)
  → completes via POST /confirm-digital or auto-confirm after 3 days (default)

Remaining payments → collected, no new order needed

Scenario 4 — Installment Purchase (AFTER_PAYMENT fulfillment)

Buyer pays all installments first, gets the product only after full payment.

Physical product:

First payment → no order created yet, agreement tracked only
...
Final payment → order created (source: INSTALLMENT)
  → status: PENDING_SHIPMENT
  → seller ships → buyer confirms → COMPLETED

Digital product:

First payment → no order created yet
...
Final payment → order created (source: INSTALLMENT → detected as DIGITAL_PURCHASE)
  → status: COMPLETEDAWAITING_BUYER_CONFIRM immediately
  → DigitalDownloadAccess created
  → buyer can download only after all installments are paid (escrow still held)
  → completes via POST /confirm-digital or auto-confirm after 3 days (default)

Scenario 5 — Group Purchase

Multiple buyers join a group for a discounted price. When the group reaches its participant goal, an order is created for every participant simultaneously.

Physical product:

Group goal reached →
  For each participant:
    → 1 order created (source: GROUP_PURCHASE)
    → status: PENDING_SHIPMENT
    → seller ships to each buyer individually
    → each buyer confirms delivery independently

Digital product:

Group goal reached →
  For each participant:
    → 1 order created (source: GROUP_PURCHASE → detected as DIGITAL_PURCHASE)
    → status: COMPLETEDAWAITING_BUYER_CONFIRM immediately
    → DigitalDownloadAccess created per participant
    → all buyers can download simultaneously (escrow still held, per buyer)
    → each buyer's order completes via their own POST /confirm-digital
      or auto-confirm after 3 days (default)

Group metadata stored on each order: groupInstanceId, groupPrice, regularPrice, savings.

Digital Download Flow (after any purchase)

Once an order with source DIGITAL_PURCHASE is created, the fulfillment service creates a DigitalDownloadAccess record per file per buyer.buyer, Theseand the order status is set to AWAITING_BUYER_CONFIRM. Files are downloadable at this point, but escrow is not yet released and the order is not yet COMPLETED. The order finishes one of two ways:

  • Buyer calls POST {base}/{orderId}/confirm-digital (endpoint 14) any time, or
  • A scheduled job auto-confirms the order after app.digital.order.auto-confirm-days (default: 3 days) — a 4-hourly cleanup sweep also catches any order whose individual job was missed (e.g. server restart).

Either path releases escrow to the seller and sets the order to COMPLETED.

DigitalDownloadAccess records themselves enforce:

Rule Configured by
Access expiry product.downloadExpiryDays (default: 365 days)
Max downloads product.maxDownloadsPerBuyer (null = unlimited)
Per-download URL TTL ~5 minutes — actually determined by FileThunder's own presigned-URL response (hardcoded)expiresInSeconds), not a hardcoded constant in the order service. Treat "5 minutes" as the current convention, not a guaranteed contract.

Frontend download flow:

Step 1 — List available files for an order:

GET api/v1/e-commerce/orders/{orderId}/downloads

Response:
[
  {
    "fileId": "f1a2b3c4-...",
    "fileName": "spring-boot-course.zip",
    "contentType": "application/zip",
    "fileSize": 524288000,
    "downloadCount": 0,
    "downloadsRemaining": 5,
    "accessExpiresAt": "2026-06-18T10:00:00",
    "canDownload": true
  }
]

Step 2 — Get a short-lived download link per file:

GET api/v1/e-commerce/orders/{orderId}/downloads/{fileId}

Response:
{
  "fileId": "f1a2b3c4-...",
  "fileName": "spring-boot-course.zip",
  "downloadUrl": "https://storage.../...?X-Amz-Expires=300&...",
  "expiresAt": "2026-05-19T11:05:00",
  "downloadsRemaining": 4,
  "downloadCount": 1
}

Step 3 — Buyer hits downloadUrl directly. The URL points to MinIO and expires in 5 minutes. Each call to Step 2 increments downloadCount.

Order Status Reference

Status Applies to Meaning
PENDING_PAYMENT—Declared on the enum but not currently used — orders are only ever created once checkout reaches PAYMENT_COMPLETED, so a persisted order never starts in this status
PENDING_SHIPMENT Physical Order paid, waiting for seller to ship
SHIPPED Physical Seller marked as shipped, waiting for buyer confirmation
DELIVEREDPhysicalDeclared on the enum but not currently assigned by any code path — confirmDelivery() jumps straight from SHIPPED to COMPLETED (it does set the deliveredAt timestamp, which is what actually drives the DELIVERED timeline step)
AWAITING_BUYER_CONFIRMDigitalOrder created, files downloadable, escrow still held — waiting for buyer confirmation (POST /confirm-digital) or the auto-confirm window (default 3 days)
COMPLETED Both Physical: buyer confirmed delivery.delivery via 6-digit code. Digital: setbuyer immediatelyconfirmed via /confirm-digital, or auto-confirmed
DISPUTEDDigital only (currently)Buyer raised a dispute while AWAITING_BUYER_CONFIRM — escrow frozen pending admin review. No code path currently raises a dispute on creationa physical (SHIPPED) order, despite the timeline reference below implying both are possible
CANCELLED Both OrderDeclared cancelledand mapped in the timeline builder, but order cancellation itself is not implemented anywhere yet (CancelProductOrderRequest/ProductOrderCancelledResponse DTOs exist but are unused) — this status is currently unreachable in practice
REFUNDED Both Payment refunded
Delivery Status Applies to Meaning
PENDING Physical Not yet shipped
IN_TRANSIT Physical Seller marked as shipped
CONFIRMED Physical Buyer confirmed receipt
NOT_APPLICABLE Digital No physical delivery involved

Timeline Reference

The timeline field is embedded in every order detail response. It is a sequential list of steps representing the order's lifecycle. Steps not yet reached have timestamp: null and isCompleted: false — the frontend renders these as pending/greyed-out.

Physical order steps (DIRECT_PURCHASE, CART_PURCHASE, INSTALLMENT, GROUP_PURCHASE):

ORDER_PLACED → SHIPPED → DELIVERED → COMPLETED

Digital order steps (DIGITAL_PURCHASE):

ORDER_PLACED → FILES_AVAILABLE → COMPLETED

Terminal branches (replace remaining steps when reached):

CANCELLED  — appears after ORDER_PLACED if cancelled before shipping
             (mapper supports rendering this branch, but order cancellation
             itself isn't implemented yet — currently unreachable)
DISPUTED   — appears after SHIPPED/FILES_AVAILABLE if buyer raises a dispute
             (digital orders only, via the DigitalProductDispute subsystem —
             no code path currently raises a dispute on a SHIPPED physical order)
REFUNDED   — appears after DISPUTED if resolved in buyer's favour

Step notes:

Step Note value
SHIPPED "<Carrier> · <TrackingNumber>" if tracking info is set, otherwise null
CANCELLED Cancellation reason if provided, otherwise null
COMPLETED "Confirmed by buyer" (buyer used the 6-digit code, or /confirm-digital) or "Auto-confirmed" depending(3-day ondigital howtimeout itjob) was— confirmeddriven by buyerConfirmedAt/autoConfirmedAt
All others null
Back to top