> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/api-reference/returns-api/returns.md).

# Returns

## GET /returns/v1/{identifier}/orders/{orderReference}/return-orders/{returnOrderNumber}

> Gets a Return Order

```json
{"openapi":"3.1.1","info":{"title":"GRP Returns API","version":"1"},"servers":[{"url":"https://api.esw.com"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","name":"Authorization","in":"header","description":"Please insert JWT with Bearer into field"}},"schemas":{"Returns.Oms.Api.UseCases.GetReturnOrder.GetReturnOrderWebResponse":{"description":"Get Return Order response object","type":"object","properties":{"contacts":{"description":"Return Order Contacts","type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.CreateReturnOrder.CreateReturnLabelDtos.ReturnContactInformationDto"}},"id":{"description":"Id","type":"string"},"status":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ReturnOrderStatus"},"returnAdminCentreCode":{"description":"Return Admin Centre Code","type":"string"},"storeReturnsCentreCode":{"description":"Store Returns Centre Code (for RTS returns)","type":"string"},"returnsListingsGuid":{"format":"uuid","description":"Returns listing guid","type":"string"},"returnType":{"$ref":"#/components/schemas/Returns.Oms.Api.UseCases.Common.ReturnType"},"returnOrderNumber":{"description":"Return order number","type":"string"},"returnMethod":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ReturnMethod"},"isPaperlessRoute":{"description":"Is paperless route","type":"boolean"},"paidBy":{"description":"Paid By","type":"string"},"carrierIdentifier":{"description":"Carrier Identifier","type":"string"},"countryCode":{"description":"Country Code (Origin Country ISO)","type":"string"},"dropOffLocation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.DropOffLocationDto"},"orderReference":{"description":"Order Reference","type":"string"},"createdOn":{"format":"date-time","description":"Date return order was created on","type":"string"},"lastUpdated":{"format":"date-time","description":"Date return order was last updated","type":"string"},"returnProcessedOn":{"format":"date-time","description":"Date return order was processed","type":"string"},"returnItems":{"description":"Return items","type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.ReturnOrderItemDto"}},"weight":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.WeightDto"},"routeCode":{"description":"RouteCode","type":"string"},"paymentInformation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.PaymentInformationDto"},"store":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.StoreDto"},"waivedShippingCost":{"description":"Waived shipping cost","type":"boolean"},"splitInformation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.SplitInformationDto"},"rejectedReturnPackage":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.UpdateReturnOrder.RejectedReturnPackageDto"},"retailerIdentifier":{"description":"Retailer Identifier","type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.CreateReturnOrder.CreateReturnLabelDtos.ReturnContactInformationDto":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ContactType"},"firstName":{"type":"string"},"lastName":{"type":"string"},"unit":{"type":"string"},"poBox":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"address3":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postalCode":{"type":"string"},"countryIso":{"type":"string"},"email":{"type":"string"},"telephone":{"type":"string"},"cultureLanguageIso":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.ContactType":{"enum":["Sender","Collection","PUDO"],"type":"string"},"Returns.Oms.Domain.Enums.ReturnOrderStatus":{"enum":["Pending","Created","Received","OnHold","Released","Processed","AddedToManifest","SentToRetailer","ReceivedByRetailer","RemovedFromManifest","Cancelled","Refunded"],"type":"string"},"Returns.Oms.Api.UseCases.Common.ReturnType":{"format":"int32","description":"Return Type Enum","enum":[1,2,3,4,5,6,7,8],"type":"integer"},"Returns.Oms.Domain.Enums.ReturnMethod":{"enum":["Postal","PUDO","Collection","Store"],"type":"string"},"Returns.Oms.Application.UseCases.Common.DropOffLocationDto":{"type":"object","properties":{"id":{"type":"string"},"type":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.LocationType"},"name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"address3":{"type":"string"},"city":{"type":"string"},"postcode":{"type":"string"},"sortcode":{"type":"string"},"region":{"type":"string"},"country":{"type":"string"},"telephone":{"type":"string"},"email":{"type":"string"},"openingTimesDescription":{"type":"string"},"openingTimes":{"type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.OpeningTimeDto"}},"carrierServiceRouteId":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.LocationType":{"enum":["Store","Pudo"],"type":"string"},"Returns.Oms.Application.UseCases.Common.OpeningTimeDto":{"type":"object","properties":{"day":{"type":"string"},"opens":{"type":"string"},"closes":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.ReturnOrderItemDto":{"type":"object","properties":{"returnItemStatus":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ReturnItemStatus"},"rejectionReason":{"type":"string"},"returnReasons":{"type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.ReturnItemReasonDto"}},"id":{"type":"string"},"productCode":{"type":"string"},"lineItemId":{"type":"string"},"productDescription":{"type":"string"},"productCustomsDescription":{"type":"string"},"countryOfOriginIso":{"type":"string"},"hsCode":{"type":"string"},"weight":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.WeightDto"},"unitPrice":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.UnitPriceDto"},"productImageUrl":{"type":"string"},"mid":{"type":"string"},"midZipCode":{"type":"string"},"color":{"type":"string"},"size":{"type":"string"},"category":{"type":"string"},"personalized":{"type":"boolean"},"dangerousGoods":{"type":"boolean"},"prohibitedForReturns":{"type":"boolean"},"shippingInformation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.ShippingInformationDto"},"grading":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.ReturnItemGradingDto"},"fulfilmentInformation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.FulfilmentInformationDto"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.ReturnItemStatus":{"enum":["InProgress","Accepted","Rejected","RejectedNotReturned","Cancelled"],"type":"string"},"Returns.Oms.Application.UseCases.Common.ReturnItemReasonDto":{"type":"object","properties":{"reasonCode":{"type":"string"},"description":{"type":"string"},"reasonComment":{"type":"string"},"isRetailerAtFault":{"type":"boolean"},"suppliedBy":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ReturnOrderParty"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.ReturnOrderParty":{"enum":["Shopper","CustomerService"],"type":"string"},"Returns.Oms.Application.UseCases.Common.WeightDto":{"type":"object","properties":{"weightTotal":{"format":"double","type":"number"},"weightUnit":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.WeightUnit"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.WeightUnit":{"enum":["Kg","Lb"],"type":"string"},"Returns.Oms.Application.UseCases.Common.UnitPriceDto":{"type":"object","properties":{"amount":{"format":"double","type":"number"},"currency":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.ShippingInformationDto":{"type":"object","properties":{"shippingReference":{"type":"string"},"shippingReferenceLastMile":{"type":"string"},"carrierReference":{"type":"string"},"barcodeReference":{"type":"string"},"shippingStatus":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ShippingStatus"},"statusDate":{"format":"date-time","type":"string"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.ShippingStatus":{"enum":["Unshipped","Shipped","Cancelled"],"type":"string"},"Returns.Oms.Application.UseCases.Common.ReturnItemGradingDto":{"type":"object","properties":{"gradingType":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.FulfilmentInformationDto":{"type":"object","properties":{"centreId":{"type":"string"},"countryIso":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.PaymentInformationDto":{"type":"object","properties":{"checkoutReference":{"type":"string"},"method":{"type":"string"},"price":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.UnitPriceDto"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.StoreDto":{"type":"object","properties":{"tenantCode":{"type":"string"},"countryCode":{"type":"string"},"id":{"type":"string"},"storeName":{"type":"string"},"storeType":{"type":"string"},"partnerName":{"type":"string"},"storeNumber":{"format":"int64","type":"integer"},"city":{"type":"string"},"region":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"addressLine3":{"type":"string"},"postalCode":{"type":"string"},"phoneNumber":{"type":"string"},"location":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.StoreLocationDto"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.StoreLocationDto":{"type":"object","properties":{"latitude":{"format":"double","type":"number"},"longitude":{"format":"double","type":"number"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.SplitInformationDto":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/Returns.Oms.Domain.Entities.SplitType"},"originalReturnOrderNumber":{"type":"string"},"splitsReturnOrderNumbers":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"Returns.Oms.Domain.Entities.SplitType":{"format":"int32","enum":[0,1],"type":"integer"},"Returns.Oms.Application.UseCases.UpdateReturnOrder.RejectedReturnPackageDto":{"type":"object","properties":{"packageNumber":{"format":"int64","type":"integer"},"carrierTrackingReference":{"type":"string"},"carrierTrackingUrl":{"type":"string"},"rejectedItemsIds":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"Microsoft.AspNetCore.Mvc.ProblemDetails":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"format":"int32","type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/returns/v1/{identifier}/orders/{orderReference}/return-orders/{returnOrderNumber}":{"get":{"tags":["Returns"],"summary":"Gets a Return Order","parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true},{"schema":{"type":"string"},"in":"path","name":"orderReference","required":true},{"schema":{"type":"string"},"in":"path","name":"returnOrderNumber","required":true}],"responses":{"200":{"description":"Successfully got return order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Returns.Oms.Api.UseCases.GetReturnOrder.GetReturnOrderWebResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"403":{"description":"Get return order is forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"404":{"description":"Return Order can't be found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"500":{"description":"A unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}}}}}}}
```

## POST /returns/v1/{identifier}/orders/{orderReference}/return-orders

> Creates a Return Order

```json
{"openapi":"3.1.1","info":{"title":"GRP Returns API","version":"1"},"servers":[{"url":"https://api.esw.com"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","name":"Authorization","in":"header","description":"Please insert JWT with Bearer into field"}},"schemas":{"Returns.Oms.Api.UseCases.CreateReturnOrder.CreateReturnOrderWebResponse":{"description":"Create Return Order WebResponse","type":"object","properties":{"returnsListingsGuid":{"format":"uuid","description":"Returns Listings Guid","type":"string"},"returnOrderNumber":{"description":"Return Order Number","type":"string"},"returnType":{"description":"Return Type","type":"string"},"returnMethod":{"description":"Return Method","type":"string"},"paidBy":{"description":"Paid By","type":"string"},"carrierIdentifier":{"description":"Carrier Identifier","type":"string"},"isPaperlessRoute":{"description":"Is paperless route","type":"boolean"},"returnItems":{"description":"Return Items","type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Api.UseCases.CreateReturnOrder.CreateReturnOrderItemWebResponse"}},"dropOffLocation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.DropOffLocationDto"},"weight":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.WeightDto"},"paymentRedirectUrl":{"description":"Payment redirect url","type":"string"},"label":{"description":"Base 64 encoded label","type":"string"}},"additionalProperties":false},"Returns.Oms.Api.UseCases.CreateReturnOrder.CreateReturnOrderItemWebResponse":{"description":"Return Item Web Response","type":"object","properties":{"id":{"description":"Id","type":"string"},"productCode":{"description":"Product code","type":"string"},"lineItemId":{"description":"Line Item Id","type":"string"},"productDescription":{"description":"Product description","type":"string"},"productImageUrl":{"description":"Product Image Url","type":"string"},"color":{"description":"Color","type":"string"},"size":{"description":"Size","type":"string"},"category":{"description":"Category","type":"string"},"reasonCode":{"description":"Reason Code","type":"string"},"dispositionId":{"description":"Disposition Id","type":"string"},"reasonComment":{"description":"Reason comment","type":"string"},"replacementInformation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.CreateReturnOrder.CreateReturnReplacementInformationDto"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.CreateReturnOrder.CreateReturnReplacementInformationDto":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.CreateReturnOrder.RequestReplacementType"},"productCode":{"type":"string"},"lineItemId":{"type":"string"},"retailerLineItemId":{"type":"string"},"productImageUrl":{"type":"string"},"color":{"type":"string"},"size":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.CreateReturnOrder.RequestReplacementType":{"enum":["ExchangeReplacement","Exchanged"],"type":"string"},"Returns.Oms.Application.UseCases.Common.DropOffLocationDto":{"type":"object","properties":{"id":{"type":"string"},"type":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.LocationType"},"name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"address3":{"type":"string"},"city":{"type":"string"},"postcode":{"type":"string"},"sortcode":{"type":"string"},"region":{"type":"string"},"country":{"type":"string"},"telephone":{"type":"string"},"email":{"type":"string"},"openingTimesDescription":{"type":"string"},"openingTimes":{"type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.OpeningTimeDto"}},"carrierServiceRouteId":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.LocationType":{"enum":["Store","Pudo"],"type":"string"},"Returns.Oms.Application.UseCases.Common.OpeningTimeDto":{"type":"object","properties":{"day":{"type":"string"},"opens":{"type":"string"},"closes":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.WeightDto":{"type":"object","properties":{"weightTotal":{"format":"double","type":"number"},"weightUnit":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.WeightUnit"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.WeightUnit":{"enum":["Kg","Lb"],"type":"string"},"Microsoft.AspNetCore.Mvc.ValidationProblemDetails":{"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"type":{"type":"string"},"title":{"type":"string"},"status":{"format":"int32","type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"additionalProperties":{}},"Microsoft.AspNetCore.Mvc.ProblemDetails":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"format":"int32","type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"additionalProperties":{}},"Returns.Oms.Api.UseCases.CreateReturnOrder.CreateReturnOrderWebRequest":{"description":"Create Return Order WebRequest","type":"object","properties":{"consumerEmailAddress":{"description":"Consumer Email Address","type":"string"},"cultureLanguageIso":{"description":"Culture Language ISO","type":"string"},"returnItems":{"description":"Return Items","type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.CreateReturnOrder.ReturnItemRequestDto"}},"returnMethod":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ReturnMethod"},"returnType":{"$ref":"#/components/schemas/Returns.Oms.Api.UseCases.Common.ReturnType"},"isPaperlessRoute":{"description":"Is paperless route","type":"boolean"},"paidBy":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.PaidBy"},"carrierIdentifier":{"description":"Carrier Identifier","type":"string"},"dropOffLocation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.DropOffLocationDto"},"shippingReference":{"description":"Shipping Reference","type":"string"},"barcodeReference":{"description":"Barcode reference","type":"string"},"carrierReference":{"description":"Barcode reference","type":"string"},"weight":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.WeightDto"},"returnAdminCentreCodeOverride":{"description":"Return admin centre code override","type":"string"},"skipRouteCode":{"description":"Skip Route Code assignment for the return if true","type":"boolean"},"skipSortationAndSplit":{"description":"If the skip flag is true, then the return order will not be split or sorted.","type":"boolean"},"collectionInformation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.CollectionInformationDto"},"returnOrderNumber":{"format":"int64","description":"Return Order Number","type":"integer"},"isSynchronousRequest":{"description":"Process the request synchronously. When true, the return order creation will complete\r\nbefore returning a response, similar to the migration endpoint behavior.","type":"boolean"},"includeInstructions":{"description":"Include instructions with LIAB label","type":"boolean"},"virtualBrandIdentifier":{"description":"Virtual brand identifier for returns partners","type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.CreateReturnOrder.ReturnItemRequestDto":{"type":"object","properties":{"reasonCode":{"type":"string"},"reasonComment":{"type":"string"},"dispositionId":{"type":"string"},"replacementInformation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.CreateReturnOrder.CreateReturnReplacementInformationDto"},"monolithId":{"type":"string"},"id":{"type":"string"},"productCode":{"type":"string"},"lineItemId":{"type":"string"},"retailerLineItemId":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.ReturnMethod":{"enum":["Postal","PUDO","Collection","Store"],"type":"string"},"Returns.Oms.Api.UseCases.Common.ReturnType":{"format":"int32","description":"Return Type Enum","enum":[1,2,3,4,5,6,7,8],"type":"integer"},"Returns.Oms.Domain.Enums.PaidBy":{"enum":["Unpaid","Retailer","Shopper"],"type":"string"},"Returns.Oms.Application.UseCases.Common.CollectionInformationDto":{"type":"object","properties":{"date":{"format":"date","type":"string"},"address":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.CollectionAddressDto"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.CollectionAddressDto":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"address3":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postalCode":{"type":"string"},"countryIso":{"type":"string"},"email":{"type":"string"},"telephone":{"type":"string"}},"additionalProperties":false}}},"paths":{"/returns/v1/{identifier}/orders/{orderReference}/return-orders":{"post":{"tags":["Returns"],"summary":"Creates a Return Order","parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true},{"schema":{"type":"string"},"in":"path","name":"orderReference","required":true}],"responses":{"201":{"description":"The Return Order has been successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Returns.Oms.Api.UseCases.CreateReturnOrder.CreateReturnOrderWebResponse"}}}},"400":{"description":"Validation has failed for Return Order creation request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails"}}}},"401":{"description":"Missing auth token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"403":{"description":"Permissions error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"404":{"description":"Tenant Code doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"500":{"description":"An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Returns.Oms.Api.UseCases.CreateReturnOrder.CreateReturnOrderWebRequest"}}},"description":"The request"}}}}}
```

## POST /returns/v1/{identifier}/return-methods/{orderReference}

> Search Return Methods

```json
{"openapi":"3.1.1","info":{"title":"GRP Returns API","version":"1"},"servers":[{"url":"https://api.esw.com"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","name":"Authorization","in":"header","description":"Please insert JWT with Bearer into field"}},"schemas":{"Returns.Oms.Api.UseCases.SearchReturnMethods.SearchReturnMethodsWebResponse":{"description":"Search Return Methods Web Response","type":"object","properties":{"orderReference":{"description":"Order Reference","type":"string"},"originCountryIso":{"description":"Origin Country Iso","type":"string"},"destinationCountryIso":{"description":"Destination Country Iso","type":"string"},"selectedReturnAdminCentreCode":{"description":"Selected return admin centre code","type":"string"},"returnMethods":{"description":"Return Methods","type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.SearchReturnMethods.ReturnMethodDto"}}},"additionalProperties":false},"Returns.Oms.Application.UseCases.SearchReturnMethods.ReturnMethodDto":{"type":"object","properties":{"returnMethod":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ReturnMethod"},"paidBy":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.PaidBy"},"shippingRate":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.SearchReturnMethods.ShippingRateDto"},"carrierServiceRoute":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.SearchReturnMethods.CarrierServiceRouteDto"},"isShippingRateWaived":{"type":"boolean"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.ReturnMethod":{"enum":["Postal","PUDO","Collection","Store"],"type":"string"},"Returns.Oms.Domain.Enums.PaidBy":{"enum":["Unpaid","Retailer","Shopper"],"type":"string"},"Returns.Oms.Application.UseCases.SearchReturnMethods.ShippingRateDto":{"type":"object","properties":{"amount":{"format":"double","type":"number"},"currency":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.SearchReturnMethods.CarrierServiceRouteDto":{"type":"object","properties":{"carrierServiceRouteId":{"type":"string"},"eswCarrierIdentifier":{"type":"string"},"carrierName":{"type":"string"},"serviceType":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ServiceType"},"carrierServiceCode":{"type":"string"},"carrierServiceName":{"type":"string"},"isPaperlessRoute":{"type":"boolean"},"isLocationRequired":{"type":"boolean"},"returnsCollections":{"type":"boolean"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.ServiceType":{"enum":["Express","Post","PUDO","Collection"],"type":"string"},"Microsoft.AspNetCore.Mvc.ValidationProblemDetails":{"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"type":{"type":"string"},"title":{"type":"string"},"status":{"format":"int32","type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"additionalProperties":{}},"Microsoft.AspNetCore.Mvc.ProblemDetails":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"format":"int32","type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"additionalProperties":{}},"Returns.Oms.Api.UseCases.SearchReturnMethods.SearchReturnMethodsWebRequest":{"description":"Search Return Methods Web Request","type":"object","properties":{"returnItems":{"description":"Return Items","type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.ReturnItemDto"}},"isShopperAtFault":{"description":"Indicates whether the shopper is at fault","type":"boolean"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.ReturnItemDto":{"type":"object","properties":{"id":{"type":"string"},"productCode":{"type":"string"},"lineItemId":{"type":"string"},"retailerLineItemId":{"type":"string"}},"additionalProperties":false}}},"paths":{"/returns/v1/{identifier}/return-methods/{orderReference}":{"post":{"tags":["Returns"],"summary":"Search Return Methods","parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true},{"schema":{"type":"string"},"in":"path","name":"orderReference","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Returns.Oms.Api.UseCases.SearchReturnMethods.SearchReturnMethodsWebResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"500":{"description":"Server Error"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Returns.Oms.Api.UseCases.SearchReturnMethods.SearchReturnMethodsWebRequest"}}},"description":"Request payload"}}}}}
```

## POST /returns/v1/{identifier}/tracking-events

> Retrieves tracking events

```json
{"openapi":"3.1.1","info":{"title":"GRP Returns API","version":"1"},"servers":[{"url":"https://api.esw.com"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","name":"Authorization","in":"header","description":"Please insert JWT with Bearer into field"}},"schemas":{"Returns.Oms.Application.UseCases.GetTrackingEvents.GetTrackingEventsResponse":{"type":"object","properties":{"milestones":{"type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.GetTrackingEvents.MilestoneResponseDto"}},"events":{"type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.GetTrackingEvents.TrackingEventDetailsResponseDto"}},"carrier":{"type":"string"},"carrierReference":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.GetTrackingEvents.MilestoneResponseDto":{"type":"object","properties":{"code":{"type":"string"},"dateTime":{"format":"date-time","type":"string"},"location":{"type":"string"},"isCurrentMilestone":{"type":"boolean"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.GetTrackingEvents.TrackingEventDetailsResponseDto":{"type":"object","properties":{"code":{"type":"string"},"dateTime":{"format":"date-time","type":"string"},"location":{"type":"string"}},"additionalProperties":false},"Microsoft.AspNetCore.Mvc.ValidationProblemDetails":{"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"type":{"type":"string"},"title":{"type":"string"},"status":{"format":"int32","type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"additionalProperties":{}},"Microsoft.AspNetCore.Mvc.ProblemDetails":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"format":"int32","type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"additionalProperties":{}},"Returns.Oms.Api.UseCases.GetTrackingEvents.GetTrackingEventsWebRequest":{"description":"Get tracking events web request","type":"object","properties":{"outboundOrderReference":{"description":"Outbound Order Reference","type":"string"},"trackingReference":{"format":"int64","description":"Tracking reference","type":"integer"},"emailAddress":{"description":"Email address","type":"string"},"isViewableByShopper":{"description":"Is viewable by shopper","type":"boolean"}},"additionalProperties":false}}},"paths":{"/returns/v1/{identifier}/tracking-events":{"post":{"tags":["Returns"],"summary":"Retrieves tracking events","parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true}],"responses":{"200":{"description":"Tracking events successfully received","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.GetTrackingEvents.GetTrackingEventsResponse"}}}},"400":{"description":"Validation has failed for GetTrackingEvents request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"404":{"description":"Tracking doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"500":{"description":"An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Returns.Oms.Api.UseCases.GetTrackingEvents.GetTrackingEventsWebRequest"}}},"description":"Request payload"}}}}}
```

## PUT /returns/v1/{tenant}/orders/{orderReference}/return-orders/{returnOrderNumber}

> Updates an Return Order.

```json
{"openapi":"3.1.1","info":{"title":"GRP Returns API","version":"1"},"servers":[{"url":"https://api.esw.com"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","name":"Authorization","in":"header","description":"Please insert JWT with Bearer into field"}},"schemas":{"Returns.Oms.Api.UseCases.UpdateReturnOrder.UpdateReturnOrderWebResponse":{"description":"Update Return Order web response.","type":"object","properties":{"contacts":{"description":"Return Order Contacts","type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.CreateReturnOrder.CreateReturnLabelDtos.ReturnContactInformationDto"}},"id":{"description":"Id","type":"string"},"status":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ReturnOrderStatus"},"returnAdminCentreCode":{"description":"Return Admin Centre Code","type":"string"},"storeReturnsCentreCode":{"description":"Store Returns Centre Code (for RTS returns)","type":"string"},"returnsListingsGuid":{"format":"uuid","description":"Returns listing guid","type":"string"},"returnType":{"$ref":"#/components/schemas/Returns.Oms.Api.UseCases.Common.ReturnType"},"returnOrderNumber":{"description":"Return order number","type":"string"},"returnMethod":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ReturnMethod"},"isPaperlessRoute":{"description":"Is paperless route","type":"boolean"},"paidBy":{"description":"Paid By","type":"string"},"carrierIdentifier":{"description":"Carrier Identifier","type":"string"},"countryCode":{"description":"Country Code (Origin Country ISO)","type":"string"},"dropOffLocation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.DropOffLocationDto"},"orderReference":{"description":"Order Reference","type":"string"},"createdOn":{"format":"date-time","description":"Date return order was created on","type":"string"},"lastUpdated":{"format":"date-time","description":"Date return order was last updated","type":"string"},"returnProcessedOn":{"format":"date-time","description":"Date return order was processed","type":"string"},"returnItems":{"description":"Return items","type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.ReturnOrderItemDto"}},"weight":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.WeightDto"},"routeCode":{"description":"RouteCode","type":"string"},"paymentInformation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.PaymentInformationDto"},"store":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.StoreDto"},"waivedShippingCost":{"description":"Waived shipping cost","type":"boolean"},"splitInformation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.SplitInformationDto"},"rejectedReturnPackage":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.UpdateReturnOrder.RejectedReturnPackageDto"},"retailerIdentifier":{"description":"Retailer Identifier","type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.CreateReturnOrder.CreateReturnLabelDtos.ReturnContactInformationDto":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ContactType"},"firstName":{"type":"string"},"lastName":{"type":"string"},"unit":{"type":"string"},"poBox":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"address3":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postalCode":{"type":"string"},"countryIso":{"type":"string"},"email":{"type":"string"},"telephone":{"type":"string"},"cultureLanguageIso":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.ContactType":{"enum":["Sender","Collection","PUDO"],"type":"string"},"Returns.Oms.Domain.Enums.ReturnOrderStatus":{"enum":["Pending","Created","Received","OnHold","Released","Processed","AddedToManifest","SentToRetailer","ReceivedByRetailer","RemovedFromManifest","Cancelled","Refunded"],"type":"string"},"Returns.Oms.Api.UseCases.Common.ReturnType":{"format":"int32","description":"Return Type Enum","enum":[1,2,3,4,5,6,7,8],"type":"integer"},"Returns.Oms.Domain.Enums.ReturnMethod":{"enum":["Postal","PUDO","Collection","Store"],"type":"string"},"Returns.Oms.Application.UseCases.Common.DropOffLocationDto":{"type":"object","properties":{"id":{"type":"string"},"type":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.LocationType"},"name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"address3":{"type":"string"},"city":{"type":"string"},"postcode":{"type":"string"},"sortcode":{"type":"string"},"region":{"type":"string"},"country":{"type":"string"},"telephone":{"type":"string"},"email":{"type":"string"},"openingTimesDescription":{"type":"string"},"openingTimes":{"type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.OpeningTimeDto"}},"carrierServiceRouteId":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.LocationType":{"enum":["Store","Pudo"],"type":"string"},"Returns.Oms.Application.UseCases.Common.OpeningTimeDto":{"type":"object","properties":{"day":{"type":"string"},"opens":{"type":"string"},"closes":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.ReturnOrderItemDto":{"type":"object","properties":{"returnItemStatus":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ReturnItemStatus"},"rejectionReason":{"type":"string"},"returnReasons":{"type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.ReturnItemReasonDto"}},"id":{"type":"string"},"productCode":{"type":"string"},"lineItemId":{"type":"string"},"productDescription":{"type":"string"},"productCustomsDescription":{"type":"string"},"countryOfOriginIso":{"type":"string"},"hsCode":{"type":"string"},"weight":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.WeightDto"},"unitPrice":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.UnitPriceDto"},"productImageUrl":{"type":"string"},"mid":{"type":"string"},"midZipCode":{"type":"string"},"color":{"type":"string"},"size":{"type":"string"},"category":{"type":"string"},"personalized":{"type":"boolean"},"dangerousGoods":{"type":"boolean"},"prohibitedForReturns":{"type":"boolean"},"shippingInformation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.ShippingInformationDto"},"grading":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.ReturnItemGradingDto"},"fulfilmentInformation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.FulfilmentInformationDto"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.ReturnItemStatus":{"enum":["InProgress","Accepted","Rejected","RejectedNotReturned","Cancelled"],"type":"string"},"Returns.Oms.Application.UseCases.Common.ReturnItemReasonDto":{"type":"object","properties":{"reasonCode":{"type":"string"},"description":{"type":"string"},"reasonComment":{"type":"string"},"isRetailerAtFault":{"type":"boolean"},"suppliedBy":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ReturnOrderParty"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.ReturnOrderParty":{"enum":["Shopper","CustomerService"],"type":"string"},"Returns.Oms.Application.UseCases.Common.WeightDto":{"type":"object","properties":{"weightTotal":{"format":"double","type":"number"},"weightUnit":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.WeightUnit"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.WeightUnit":{"enum":["Kg","Lb"],"type":"string"},"Returns.Oms.Application.UseCases.Common.UnitPriceDto":{"type":"object","properties":{"amount":{"format":"double","type":"number"},"currency":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.ShippingInformationDto":{"type":"object","properties":{"shippingReference":{"type":"string"},"shippingReferenceLastMile":{"type":"string"},"carrierReference":{"type":"string"},"barcodeReference":{"type":"string"},"shippingStatus":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ShippingStatus"},"statusDate":{"format":"date-time","type":"string"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.ShippingStatus":{"enum":["Unshipped","Shipped","Cancelled"],"type":"string"},"Returns.Oms.Application.UseCases.Common.ReturnItemGradingDto":{"type":"object","properties":{"gradingType":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.FulfilmentInformationDto":{"type":"object","properties":{"centreId":{"type":"string"},"countryIso":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.PaymentInformationDto":{"type":"object","properties":{"checkoutReference":{"type":"string"},"method":{"type":"string"},"price":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.UnitPriceDto"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.StoreDto":{"type":"object","properties":{"tenantCode":{"type":"string"},"countryCode":{"type":"string"},"id":{"type":"string"},"storeName":{"type":"string"},"storeType":{"type":"string"},"partnerName":{"type":"string"},"storeNumber":{"format":"int64","type":"integer"},"city":{"type":"string"},"region":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"addressLine3":{"type":"string"},"postalCode":{"type":"string"},"phoneNumber":{"type":"string"},"location":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.StoreLocationDto"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.StoreLocationDto":{"type":"object","properties":{"latitude":{"format":"double","type":"number"},"longitude":{"format":"double","type":"number"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.SplitInformationDto":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/Returns.Oms.Domain.Entities.SplitType"},"originalReturnOrderNumber":{"type":"string"},"splitsReturnOrderNumbers":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"Returns.Oms.Domain.Entities.SplitType":{"format":"int32","enum":[0,1],"type":"integer"},"Returns.Oms.Application.UseCases.UpdateReturnOrder.RejectedReturnPackageDto":{"type":"object","properties":{"packageNumber":{"format":"int64","type":"integer"},"carrierTrackingReference":{"type":"string"},"carrierTrackingUrl":{"type":"string"},"rejectedItemsIds":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"Microsoft.AspNetCore.Mvc.ValidationProblemDetails":{"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"type":{"type":"string"},"title":{"type":"string"},"status":{"format":"int32","type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"additionalProperties":{}},"Microsoft.AspNetCore.Mvc.ProblemDetails":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"format":"int32","type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"additionalProperties":{}},"Returns.Oms.Api.UseCases.UpdateReturnOrder.UpdateReturnOrderWebRequest":{"description":"Update Return Order web request.","type":"object","properties":{"status":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ReturnOrderStatus"},"statusReason":{"description":"Return order status reason","type":"string"},"returnItems":{"description":"Return Items","type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.UpdateReturnOrder.UpdateReturnOrderItemDto"}},"weight":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.WeightDto"},"skipSortationAndSplit":{"description":"if the skip flag equal true then the return order will not be spilled or sorted.","type":"boolean"},"addItemForOnHold":{"description":"If true, bypasses the validation of the return item processed status.","type":"boolean"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.UpdateReturnOrder.UpdateReturnOrderItemDto":{"type":"object","properties":{"returnItemStatus":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.UpdateReturnOrder.UpdateReturnItemStatus"},"rejectionReason":{"type":"string"},"reasonCodeOverride":{"type":"string"},"reasonCode":{"type":"string"},"grading":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.ReturnItemGradingDto"},"id":{"type":"string"},"productCode":{"type":"string"},"lineItemId":{"type":"string"},"retailerLineItemId":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.UpdateReturnOrder.UpdateReturnItemStatus":{"enum":["InProgress","Accepted","Rejected"],"type":"string"}}},"paths":{"/returns/v1/{tenant}/orders/{orderReference}/return-orders/{returnOrderNumber}":{"put":{"tags":["Returns"],"summary":"Updates an Return Order.","parameters":[{"schema":{"type":"string"},"in":"path","name":"tenant","required":true},{"schema":{"type":"string"},"in":"path","name":"orderReference","required":true},{"schema":{"type":"string"},"in":"path","name":"returnOrderNumber","required":true}],"responses":{"200":{"description":"Successfully processed Return Order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Returns.Oms.Api.UseCases.UpdateReturnOrder.UpdateReturnOrderWebResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"403":{"description":"Put Return Order is forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"404":{"description":"Return Order can't be found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"500":{"description":"A unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Returns.Oms.Api.UseCases.UpdateReturnOrder.UpdateReturnOrderWebRequest"}}},"description":"Return order data"}}}}}
```

## GET /returns/v1/{identifier}/return-orders

> Retrieves a list of return orders based on provided criteria

```json
{"openapi":"3.1.1","info":{"title":"GRP Returns API","version":"1"},"servers":[{"url":"https://api.esw.com"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","name":"Authorization","in":"header","description":"Please insert JWT with Bearer into field"}},"schemas":{"Returns.Oms.Api.UseCases.GetReturnOrder.GetReturnOrderWebResponse":{"description":"Get Return Order response object","type":"object","properties":{"contacts":{"description":"Return Order Contacts","type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.CreateReturnOrder.CreateReturnLabelDtos.ReturnContactInformationDto"}},"id":{"description":"Id","type":"string"},"status":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ReturnOrderStatus"},"returnAdminCentreCode":{"description":"Return Admin Centre Code","type":"string"},"storeReturnsCentreCode":{"description":"Store Returns Centre Code (for RTS returns)","type":"string"},"returnsListingsGuid":{"format":"uuid","description":"Returns listing guid","type":"string"},"returnType":{"$ref":"#/components/schemas/Returns.Oms.Api.UseCases.Common.ReturnType"},"returnOrderNumber":{"description":"Return order number","type":"string"},"returnMethod":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ReturnMethod"},"isPaperlessRoute":{"description":"Is paperless route","type":"boolean"},"paidBy":{"description":"Paid By","type":"string"},"carrierIdentifier":{"description":"Carrier Identifier","type":"string"},"countryCode":{"description":"Country Code (Origin Country ISO)","type":"string"},"dropOffLocation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.DropOffLocationDto"},"orderReference":{"description":"Order Reference","type":"string"},"createdOn":{"format":"date-time","description":"Date return order was created on","type":"string"},"lastUpdated":{"format":"date-time","description":"Date return order was last updated","type":"string"},"returnProcessedOn":{"format":"date-time","description":"Date return order was processed","type":"string"},"returnItems":{"description":"Return items","type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.ReturnOrderItemDto"}},"weight":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.WeightDto"},"routeCode":{"description":"RouteCode","type":"string"},"paymentInformation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.PaymentInformationDto"},"store":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.StoreDto"},"waivedShippingCost":{"description":"Waived shipping cost","type":"boolean"},"splitInformation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.SplitInformationDto"},"rejectedReturnPackage":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.UpdateReturnOrder.RejectedReturnPackageDto"},"retailerIdentifier":{"description":"Retailer Identifier","type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.CreateReturnOrder.CreateReturnLabelDtos.ReturnContactInformationDto":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ContactType"},"firstName":{"type":"string"},"lastName":{"type":"string"},"unit":{"type":"string"},"poBox":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"address3":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postalCode":{"type":"string"},"countryIso":{"type":"string"},"email":{"type":"string"},"telephone":{"type":"string"},"cultureLanguageIso":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.ContactType":{"enum":["Sender","Collection","PUDO"],"type":"string"},"Returns.Oms.Domain.Enums.ReturnOrderStatus":{"enum":["Pending","Created","Received","OnHold","Released","Processed","AddedToManifest","SentToRetailer","ReceivedByRetailer","RemovedFromManifest","Cancelled","Refunded"],"type":"string"},"Returns.Oms.Api.UseCases.Common.ReturnType":{"format":"int32","description":"Return Type Enum","enum":[1,2,3,4,5,6,7,8],"type":"integer"},"Returns.Oms.Domain.Enums.ReturnMethod":{"enum":["Postal","PUDO","Collection","Store"],"type":"string"},"Returns.Oms.Application.UseCases.Common.DropOffLocationDto":{"type":"object","properties":{"id":{"type":"string"},"type":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.LocationType"},"name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"address3":{"type":"string"},"city":{"type":"string"},"postcode":{"type":"string"},"sortcode":{"type":"string"},"region":{"type":"string"},"country":{"type":"string"},"telephone":{"type":"string"},"email":{"type":"string"},"openingTimesDescription":{"type":"string"},"openingTimes":{"type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.OpeningTimeDto"}},"carrierServiceRouteId":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.LocationType":{"enum":["Store","Pudo"],"type":"string"},"Returns.Oms.Application.UseCases.Common.OpeningTimeDto":{"type":"object","properties":{"day":{"type":"string"},"opens":{"type":"string"},"closes":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.ReturnOrderItemDto":{"type":"object","properties":{"returnItemStatus":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ReturnItemStatus"},"rejectionReason":{"type":"string"},"returnReasons":{"type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.ReturnItemReasonDto"}},"id":{"type":"string"},"productCode":{"type":"string"},"lineItemId":{"type":"string"},"productDescription":{"type":"string"},"productCustomsDescription":{"type":"string"},"countryOfOriginIso":{"type":"string"},"hsCode":{"type":"string"},"weight":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.WeightDto"},"unitPrice":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.UnitPriceDto"},"productImageUrl":{"type":"string"},"mid":{"type":"string"},"midZipCode":{"type":"string"},"color":{"type":"string"},"size":{"type":"string"},"category":{"type":"string"},"personalized":{"type":"boolean"},"dangerousGoods":{"type":"boolean"},"prohibitedForReturns":{"type":"boolean"},"shippingInformation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.ShippingInformationDto"},"grading":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.ReturnItemGradingDto"},"fulfilmentInformation":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.FulfilmentInformationDto"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.ReturnItemStatus":{"enum":["InProgress","Accepted","Rejected","RejectedNotReturned","Cancelled"],"type":"string"},"Returns.Oms.Application.UseCases.Common.ReturnItemReasonDto":{"type":"object","properties":{"reasonCode":{"type":"string"},"description":{"type":"string"},"reasonComment":{"type":"string"},"isRetailerAtFault":{"type":"boolean"},"suppliedBy":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ReturnOrderParty"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.ReturnOrderParty":{"enum":["Shopper","CustomerService"],"type":"string"},"Returns.Oms.Application.UseCases.Common.WeightDto":{"type":"object","properties":{"weightTotal":{"format":"double","type":"number"},"weightUnit":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.WeightUnit"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.WeightUnit":{"enum":["Kg","Lb"],"type":"string"},"Returns.Oms.Application.UseCases.Common.UnitPriceDto":{"type":"object","properties":{"amount":{"format":"double","type":"number"},"currency":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.ShippingInformationDto":{"type":"object","properties":{"shippingReference":{"type":"string"},"shippingReferenceLastMile":{"type":"string"},"carrierReference":{"type":"string"},"barcodeReference":{"type":"string"},"shippingStatus":{"$ref":"#/components/schemas/Returns.Oms.Domain.Enums.ShippingStatus"},"statusDate":{"format":"date-time","type":"string"}},"additionalProperties":false},"Returns.Oms.Domain.Enums.ShippingStatus":{"enum":["Unshipped","Shipped","Cancelled"],"type":"string"},"Returns.Oms.Application.UseCases.Common.ReturnItemGradingDto":{"type":"object","properties":{"gradingType":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.FulfilmentInformationDto":{"type":"object","properties":{"centreId":{"type":"string"},"countryIso":{"type":"string"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.PaymentInformationDto":{"type":"object","properties":{"checkoutReference":{"type":"string"},"method":{"type":"string"},"price":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.UnitPriceDto"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.StoreDto":{"type":"object","properties":{"tenantCode":{"type":"string"},"countryCode":{"type":"string"},"id":{"type":"string"},"storeName":{"type":"string"},"storeType":{"type":"string"},"partnerName":{"type":"string"},"storeNumber":{"format":"int64","type":"integer"},"city":{"type":"string"},"region":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"addressLine3":{"type":"string"},"postalCode":{"type":"string"},"phoneNumber":{"type":"string"},"location":{"$ref":"#/components/schemas/Returns.Oms.Application.UseCases.Common.StoreLocationDto"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.StoreLocationDto":{"type":"object","properties":{"latitude":{"format":"double","type":"number"},"longitude":{"format":"double","type":"number"}},"additionalProperties":false},"Returns.Oms.Application.UseCases.Common.SplitInformationDto":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/Returns.Oms.Domain.Entities.SplitType"},"originalReturnOrderNumber":{"type":"string"},"splitsReturnOrderNumbers":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"Returns.Oms.Domain.Entities.SplitType":{"format":"int32","enum":[0,1],"type":"integer"},"Returns.Oms.Application.UseCases.UpdateReturnOrder.RejectedReturnPackageDto":{"type":"object","properties":{"packageNumber":{"format":"int64","type":"integer"},"carrierTrackingReference":{"type":"string"},"carrierTrackingUrl":{"type":"string"},"rejectedItemsIds":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"Microsoft.AspNetCore.Mvc.ValidationProblemDetails":{"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"type":{"type":"string"},"title":{"type":"string"},"status":{"format":"int32","type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"additionalProperties":{}},"Microsoft.AspNetCore.Mvc.ProblemDetails":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"format":"int32","type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/returns/v1/{identifier}/return-orders":{"get":{"tags":["Returns"],"summary":"Retrieves a list of return orders based on provided criteria","parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true}],"responses":{"200":{"description":"Return orders found","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Returns.Oms.Api.UseCases.GetReturnOrder.GetReturnOrderWebResponse"}}}}},"400":{"description":"Bad request - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"403":{"description":"Request is forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"404":{"description":"Could not find any return orders based on provided criteria","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"500":{"description":"An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}}}}}}}
```

## GET /returns/v1/{identifier}/return-orders/{returnOrderNumber}/{documentType}

> Get Document

```json
{"openapi":"3.1.1","info":{"title":"GRP Returns API","version":"1"},"servers":[{"url":"https://api.esw.com"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","name":"Authorization","in":"header","description":"Please insert JWT with Bearer into field"}},"schemas":{"Returns.Documentation.Domain.Models.DocumentDetails":{"type":"object","properties":{"orderReference":{"type":"string"},"returnOrderNumber":{"type":"string"},"contentType":{"type":"string"},"documentStatus":{"$ref":"#/components/schemas/Returns.Documentation.Domain.Enums.ReturnDocumentStatus"},"label":{"type":"string"},"cultureLanguageIso":{"type":"string"},"documentId":{"format":"uuid","type":"string"},"documentType":{"$ref":"#/components/schemas/Returns.Documentation.Domain.Models.ReturnDocumentType"},"carrierInfoDetails":{"$ref":"#/components/schemas/Returns.Documentation.Domain.Models.CarrierInfoDetails"}},"additionalProperties":false},"Returns.Documentation.Domain.Enums.ReturnDocumentStatus":{"enum":["Processing","Ready","Failed"],"type":"string"},"Returns.Documentation.Domain.Models.ReturnDocumentType":{"enum":["ReturnLabel","LastMileLabel","PrePrintedLabel","RejectedReturnLabel"],"type":"string"},"Returns.Documentation.Domain.Models.CarrierInfoDetails":{"type":"object","properties":{"carrierId":{"type":"string"},"carrierName":{"type":"string"},"carrierReference":{"type":"string"},"carrierTrackingReference":{"type":"string"}},"additionalProperties":false},"Microsoft.AspNetCore.Mvc.ProblemDetails":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"format":"int32","type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"additionalProperties":{}},"Returns.Documentation.Domain.Models.BaseResponse":{"type":"object","properties":{"userMessage":{"type":"string"},"details":{"type":"string"}},"additionalProperties":false}}},"paths":{"/returns/v1/{identifier}/return-orders/{returnOrderNumber}/{documentType}":{"get":{"tags":["Returns"],"summary":"Get Document","parameters":[{"schema":{"type":"string"},"in":"path","name":"identifier","required":true},{"schema":{"type":"string"},"in":"path","name":"returnOrderNumber","required":true},{"schema":{"type":"string"},"in":"path","name":"documentType","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Returns.Documentation.Domain.Models.DocumentDetails"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Returns.Documentation.Domain.Models.BaseResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.esw.com/api-reference/returns-api/returns.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.