Order module RMA and shipment API handler

3 min

POST RMA (Add)

HTTP Verb – POST

URL – /api/v1/orders//returns

Description – Submit a new Return Merchandise Authorization request

Base – HandlerBase\<AddRmaParameter, AddRmaResult\>

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.

HTTP Verb – N/A (internal service call)

Description – Get a collection of shipments for an order

Base – HandlerBase\<GetShipmentCollectionParameter, GetShipmentCollectionResult\>

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.

HTTP Verb – N/A (internal service call)

Description – Get a single shipment by shipment number

Base – HandlerBase\<GetShipmentParameter, GetShipmentResult\>

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.