Plugin Requirements

Since WooCommerce is an open source platform, this means that we can build on top of it.

Their native REST APIs do not currently provide native support for partial shipments or returns. Partial shipment and returns functionality is typically handled by third-party plugins, which add custom order statuses, shipment tracking, and API endpoints for managing partial shipment.

We need to build a plugin which will help us handle the above mentioned flows.The plugin will be built as a native WordPress/WooCommerce extension, maintaining data integrity through custom database tables. The plugin must integrate seamlessly with WooCommerce's existing order management workflow without disrupting standard operations.

We want to start with building up a basic handler that will allow us to control the flows via API, so the plugin must have API endpoints incorporated.The REST API will follow RESTful design principles and maintain consistency with WooCommerce's existing API patterns. All endpoints will use appropriate HTTP methods. We only want to use GET and POST methods. The methods should return meaningful HTTP status codes to indicate operation success or failure.

Partial Shipments

With the plugin, we should be able to partially ship an order including shipping individual items or partial quantities of items. We should be able to send separate tracking info per item/quantity if doing partial shipments. The tracking info that we want to send is - Tracking Number, Tracking URL and Tracking provider. The tracking number and tracking provider should be required, the URL should be optional.

We should also have automatic customer notification emails with tracking info once an order is shipped/partially shipped. A new order status of "Partially Shipped" should be introduced.Automatic status change from "Processing" > "Partially Shipped" > "Completed" with the possibility of manual override capability for order statuses.

Shipments API Implementation

The shipments API will provide Create and Read operations for shipment management. Creating shipments through the API will require a JSON payload specifying the items and quantities to be shipped, along with optional tracking information. The API will validate that requested quantities are available and do not exceed order limits before creating the shipment record.

Sample suggestion for payload that the endpoint should accept/return (depending if a POST or GET call was performed)

{
  "tracking_number": "1Z999AA10123456789",
  "tracking_provider": "UPS",
  "tracking_url": "https://example.com/track/1Z999AA10123456789",
  "line_items": [
    {
      "id": 10,
      "quantity": 2
    },
    {
      "id": 15,
      "quantity": 1
    }
  ]  
}

Returns

The users should be able to request returns for specific items or quantities. Customers will be able to initiate return requests for specific items and quantities through their account dashboard, while administrators will have full control over the approval and processing workflow. Return requests will include reason for return and customer notes on a free text basis, so no pre-defined reasons will be needed. The system will enforce configurable time limits for return eligibility, automatically preventing return requests for orders that exceed the merchant's return policy timeframe. This should be controlled from a Return Policy field in a new table in WooCommerce’s settings called “Returns”. We should also have an option called “Automatically Accept Returns” which should act as automatic return approval, meaning when the user requests a return, it gets automatically approved.

The system will track return status through a defined workflow: Pending (initial request), Approved (merchant accepts return), In Transit (customer has shipped items), Received (merchant has received items), and Completed (refund is processed).

Returns API Implementation

The returns API will mirror the structure and functionality of the shipments API while accommodating the additional complexity of return workflow management. We only want to implement Read and Update operations.

Sample suggestion for GET returns payload

GET /wp-json/wc/v3/orders/returns

{
  "id": 456, // ID of the return
  "order_id": 123 //  ID of the order  
  "status": "pending",
  "date_created_gmt": "2025-06-03T14:30:00",  
  "return_reason": "Items arrived damaged",  // Free text return reason
  "items": [
    {
      "id": 234, // ID of the product   
      "product_name": "Blue Cotton T-Shirt - Large",
      "sku": "TSH-BLU-L-001",
      "quantity": 1
    },
    {
      "id": 235,      
      "product_name": "Premium Baseball Cap",
      "sku": "CAP-PRM-001",
      "quantity": 1
    }
  ]
}

We should be able to return multiple orders’ returns with the GET method.

Sample suggestion for POST accept/reject return payload

POST /wp-json/wc/v3/orders/returns/{returnID}/approve POST /wp-json/wc/v3/orders/returns/{returnID}/reject

{
  "status": "approved",
  "notes": "Approved after reviewing customer photos"
}

{
  "status": "rejeted",
  "notes": "Return rejected"
}

User Interface Implementation

The plugin will also alter the WooCommerce orders’ UI. The administrative interface will integrate with WooCommerce's existing order management interface through the addition of custom meta boxes on the order edit screen. These meta boxes will provide visibility into shipment and return status without requiring navigation to separate screens.

The shipments meta box will display a comprehensive view of all shipments associated with an order, including shipped quantities and tracking information. Administrators will be able to create new shipments directly from this interface, with dropdown selections for items and quantity inputs that are dynamically validated against available inventory.

The returns meta box will show all return requests associated with an order, with clear status indicators and quick action buttons for common operations like approving or rejecting returns. The interface will provide one-click access to detailed return information and refund processing capabilities.

Customer-Facing Interface Implementation

The customer interface will extend WooCommerce's existing "My Account" area with new sections for shipment tracking and return management. The shipments section will provide customers with real-time visibility into their order's fulfillment status, including tracking information and expected delivery dates.

The returns section will serve as a comprehensive portal for return management, allowing customers to view the status of existing returns and initiate new return requests. The return request interface will be intuitive and guided, with clear explanations of the return process and policy.

Order detail pages will be enhanced to show shipment and return information inline with the order summary. Customers will see which items have been shipped, which are pending shipment, and which items are eligible for return based on the merchant's return policy.