Skip to content

API Documentation: Order Tracking and Status Update

OrderTrackingSerializer

Overview

The OrderTrackingSerializer is responsible for serializing and deserializing data related to order tracking. It includes various fields that represent the order's status and timeline events like when the order was confirmed, shipped, or delivered.

Fields

  • order_id: The order's unique identifier.
  • transaction: The transaction details related to the order.
  • order_status: The current status of the order.
  • ship_to: The shipping address, formatted as a dictionary containing details like name, address, mobile number, etc.
  • min_estimated_delivery_date: Estimated delivery date, calculated as 7 days from the order creation date.
  • max_estimated_delivery_date: Estimated delivery date, calculated as 10 days from the order creation date.
  • order_confirmed_at: The datetime when the order was confirmed.
  • cancelled_at: The datetime when the order was cancelled.
  • shipped_at: The datetime when the order was shipped.
  • outfor_delivery_at: The datetime when the order is out for delivery.
  • delivered_at: The datetime when the order was delivered.
  • delivery_failed_at: The datetime when the delivery failed.
  • returned_at: The datetime when the order was returned.
  • created_at: The datetime when the order was created.
  • updated_at: The datetime when the order was last updated.
  • product_info: A list containing detailed information about the products in the order.
  • product_detail: Product details associated with the order.

Methods

  • format_datetime(date): A helper method that formats the given datetime as a string in MM-DD-YYYY HH:MM:SS format.
  • format_date(date): A helper method that formats the given date as a string in MM-DD-YYYY format.
  • get_ship_to(obj): Retrieves and formats the shipping address for the order.
  • get_min_estimated_delivery_date(obj): Calculates the estimated minimum delivery date (7 days from created_at).
  • get_max_estimated_delivery_date(obj): Calculates the estimated maximum delivery date (10 days from created_at).
  • get_order_confirmed_at(obj): Returns the order_confirmed_at field formatted as datetime.
  • get_cancelled_at(obj): Returns the cancelled_at field formatted as date.
  • get_shipped_at(obj): Returns the shipped_at field formatted as date.
  • get_outfor_delivery_at(obj): Returns the outfor_delivery_at field formatted as date.
  • get_delivered_at(obj): Returns the delivered_at field formatted as date.
  • get_delivery_failed_at(obj): Returns the delivery_failed_at field formatted as date.
  • get_returned_at(obj): Returns the returned_at field formatted as date.
  • get_created_at(obj): Returns the created_at field formatted as datetime.
  • get_updated_at(obj): Returns the updated_at field formatted as datetime.
  • get_product_info(obj): Fetches product details, applies customized pricing, and calculates coupon discounts.
  • validate(attrs): Custom validation logic for order status transitions based on the current status.
  • update(instance, validated_data): Updates the order status and other relevant fields based on the new status.

OrderTrackingViewSet

Overview

The OrderTrackingViewSet provides CRUD operations for managing order tracking records. It supports filtering by role (user, vendor, or vendor role) and allows for order status updates through a custom action.

Permissions

  • permission_classes: Only users with the HasVendorRolePermission are allowed to perform specific operations.
  • required_role_name: The role Order Management is required to access the order tracking features.

Methods

1. get_queryset(self)

Filters OrderTracking objects based on the logged-in user's role and query parameters: - User: Filters orders associated with the logged-in user's purchased products. - Vendor: Filters orders belonging to the vendor's shop. - Vendor Role: Filters orders associated with the vendor assigned to the logged-in user’s vendor role.

Query parameters can be used to filter the results further: - q: Full-text search for order ID or product name. - order_id: Filter by specific order ID. - order_status: Filter by order status. - status: Filter by vendor's order status. - start_date, end_date: Filter by order creation date range. - category, subcategory: Filter by product category or subcategory.

2. list(self, request, *args, **kwargs)

Handles GET requests to list all order tracking records. Optionally, an order ID can be passed to retrieve only one order's data.

  • Response: Returns a paginated list of order tracking records, or a single order if order_id is provided.
  • Response Body: 
      [
      {
          "id": 1,
          "order_id": "12345",
          "product_info": [...],
          "product_detail": {...},
          "transaction": {...},
          "order_status": {...},
          "ship_to": {...},
          "order_confirmed_at": "01-15-2025 14:30:00",
          "cancelled_at": "01-18-2025",
          "shipped_at": "01-19-2025",
          "outfor_delivery_at": "01-20-2025",
          "delivered_at": "01-21-2025",
          "delivery_failed_at": null,
          "returned_at": null,
          "created_at": "01-15-2025",
          "updated_at": "01-20-2025",
          "min_estimated_delivery_date": "01-22-2025",
          "max_estimated_delivery_date": "01-25-2025"
      }
  ]

3. update_status(self, request, *args, **kwargs)

Custom action to update the status of an order. This endpoint only allows vendors or users with the Order Management role to update the status.

  • Request body: 

    {
  "order_id": "<order_id>",
  "new_status": "<new_status>"
}

  • Response Body: 

    {
  "message": "Order moved to <new_status>."
}