--- title: Order module RMA and shipment API handler slug: configured-commerce/docs/order-module-rma-and-shipment-api-handler docTags: createdAt: 2026-08-13T10:46:23.000Z --- ## POST RMA (Add) **HTTP Verb** – POST **URL** – /api/v1/orders//returns **Description** – Submit a new Return Merchandise Authorization request **Base** – `HandlerBase\` **Handlers** – | Order | Handler | Description | | ----- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 500 | `ValidateContext` | Verifies the current user is logged in (`UserProfileDto` is not `null`) and has a `BillTo` customer assigned. Returns `NotFound` error if either is missing. | | 600 | `ValidateRma` | Retrieves the `OrderHistory` matching the current customer's `CustomerNumber` and the specified `OrderNumber` (checks both `WebOrderNumber` and `ErpOrderNumber`). Returns `NotFound` if the order is not found. Validates that at least one RMA line has a quantity requested. For each RMA line, validates the requested quantity is greater than zero, does not exceed `QtyOrdered`, and that a return reason code is provided when reason codes are configured. | | 700 | `PopulateEmailModel` | Builds a dynamic email model containing order details (`OrderNumber`, `OrderDate`, PONumber, Notes, billing address fields) and a collection of order line items with their RMA quantities and return reasons. | | 800 | `SendEmail` | Sends the RMA request email using the "`RequestRma`" email list. Sends to both the configured `RmaDestinationEmail` and the current user's email address, using the populated email model as the template data. | ## GET Shipment Collection **HTTP Verb** – N/A (internal service call) **Description** – Get a collection of shipments for an order **Base** – `HandlerBase\` **Handlers** – | Order | Handler | Description | | ----- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 500 | `GetShipmentQuery` | Creates a query for Shipment entities (with `ShipmentPackages` included) filtered by either `WebOrderNumber` or `ErpOrderNumber` from the parameter. | | 600 | `ApplySort` | Sorts the shipment query by the parameter Sort value. If Sort is not specified, defaults to sorting by `ShipmentNumber`. | | 700 | `ApplyPaging` | Applies standard paging to the shipment query using the base `ApplyPaging` method. | | 800 | `ExecuteQuery` | Executes the query by calling `ToList()` and sets the result to the Shipments collection. | | 900 | `CreateShipmentDtos` | For each shipment in the collection, calls `ShipmentService.GetShipment` to create a detailed `ShipmentDto` (including package lines if requested). Returns error if any individual shipment retrieval fails. | ## GET Shipment **HTTP Verb** – N/A (internal service call) **Description** – Get a single shipment by shipment number **Base** – `HandlerBase\` **Handlers** – | Order | Handler | Description | | ----- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 500 | `GetShipment` | Retrieves the Shipment entity either from the parameter (if pre-loaded) or by querying the repository by `ShipmentNumber` (includes `ShipmentPackages`). Returns `NotFound` error if not found. Maps the Shipment to a `ShipmentDto` and processes shipment package details including package lines and tracking URLs via the shipment package utilities. |