> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.feedonomics.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.feedonomics.com/_mcp/server. # Create a return PUT https://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/{mp_order_number}/returns/{mp_return_number} Content-Type: application/json Get all seller-initiated refunds for an order Reference: https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/returns/create-order-returns ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `mp_order_number` (string, required) — The unique Id for an order that is generated by the marketplace - `mp_return_number` (string, required) — The unique Id for the return that is generated by the marketplace ### Body (application/json) This endpoint expects a ReturnModel. - `mp_order_number` (string, required) — the mp order number associated with the return - `return_lines` (list of ReturnLine, required) - `request_date` (date, optional) — Date the return was requested. ISO 8601 DATE YYYY-MM-DD - `respond_date` (date, optional) — The date which the merchant must release the funds by - `shipping_address` (StreetAddress, optional) - `customer_email` (string, optional) — The customer's email address - `return_type` (enum, optional) — How the items will be returned by the customer. SHIP - the item will be shipped back by the customer NO\_RETURN - The customer will kep the item IN\_STORE - the item will be returned to the store by the customer (is only valid for V2) - Allowed values: `SHIP`, `IN_STORE`, `NO_RETURN` ## Response ### 204 Return created ## Errors ### 400 Bad Request Error The request could not be completed - `list of FeedAMPReturnError` ### 401 Unauthorized Error Invalid token - `error` (string, optional) — Message describing the authentication failure ### 404 Not Found Error The order could not be found in the systems - `message` (string, optional) — Error message ## Types ### ReturnLine - `mp_return_line_number` (string, required) — The marketplace identifier of this unique return line - `mp_order_line_number` (string, required) — The marketplace identifier for the original mp order line returned - `sku` (string, required) — The sku of item being returned - `quantity` (integer, required) — The number of items being returned - `currency` (enum, required) — ISO 4217 Currency codes - Allowed values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `CNY`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL` - `requested_refund_principal` (double, required) — The requested refund amount - `reason` (string, required) — The customer's reason for the return - `preauthorized` (boolean, required) — Indicate if the seller must authorize the return False - the seller must authorize the return True - the return is already authorized. If the marketplace requires the full requested refund amount to be refunded, the return is complete - `product_name` (string, optional) — The product name of the item being returned - `unit_price` (double, optional) — The returned item's price (not including tax, shipping, or discounts) - `tax` (double, optional) — The amount of taxes that were levied against the order line - `requested_refund_tax` (double, optional) — Requested tax refund amount. - `carrier` (enum, optional) — Carrier used by seller for shipping. Must be a valid carrier name - Allowed values: `4PX`, `A-1`, `AAA Cooper`, `ABF`, `Asendia`, `Best Buy`, `Blue Package`, `Canada Post`, `CEVA`, `China Post`, `Conway`, `DHL`, `DHL eCommerce`, `Estes`, `FedEx`, `Fedex Freight`, `FedEx SmartPost`, `First Mile`, `Hongkong Post`, `Hunter Logistics`, `India Post`, `JCEX`, `Lasership`, `Newgistics`, `Old Dominion`, `OnTrac`, `OSM`, `Pilot Freight`, `R+L`, `Roadrunner`, `Royal Mail`, `Saia`, `SF Express`, `SFC`, `Singapore Post`, `South Eastern Freight Lines`, `Streamlite`, `UPS`, `UPS Freight`, `UPS Mail Innovations`, `Urban Express`, `USPS`, `WanbExpress`, `Watkins and Shepard`, `YANWEN`, `Yellow Freight`, `Yun Express`, `Other` - `tracking_number` (string, optional) — Tracking number of the item being returned ### StreetAddress - `full_name` (string, required) — Name of primary recipient - `address1` (string, required) — Street address, line 1 - `city` (string, required) — Address (City) - `state` (string, required) — Address (State or Province) - `postal_code` (string, required) — Address (Postal or Zip code) - `country_code` (enum, required) — ISO 3166-1 alpha-3 country codes - Allowed values: `ABW`, `AFG`, `AGO`, `AIA`, `ALA`, `ALB`, `AND`, `ARE`, `ARG`, `ARM`, `ASM`, `ATA`, `ATF`, `ATG`, `AUS`, `AUT`, `AZE`, `BDI`, `BEL`, `BEN`, `BES`, `BFA`, `BGD`, `BGR`, `BHR`, `BHS`, `BIH`, `BLM`, `BLR`, `BLZ`, `BMU`, `BOL`, `BRA`, `BRB`, `BRN`, `BTN`, `BVT`, `BWA`, `CAF`, `CAN`, `CCK`, `CHE`, `CHL`, `CHN`, `CIV`, `CMR`, `COD`, `COG`, `COK`, `COL`, `COM`, `CPV`, `CRI`, `CUB`, `CUW`, `CXR`, `CYM`, `CYP`, `CZE`, `DEU`, `DJI`, `DMA`, `DNK`, `DOM`, `DZA`, `ECU`, `EGY`, `ERI`, `ESH`, `ESP`, `EST`, `ETH`, `FIN`, `FJI`, `FLK`, `FRA`, `FRO`, `FSM`, `GAB`, `GBR`, `GEO`, `GGY`, `GHA`, `GIB`, `GIN`, `GLP`, `GMB`, `GNB`, `GNQ`, `GRC`, `GRD`, `GRL`, `GTM`, `GUF`, `GUM`, `GUY`, `HKG`, `HMD`, `HND`, `HRV`, `HTI`, `HUN`, `IDN`, `IMN`, `IND`, `IOT`, `IRL`, `IRN`, `IRQ`, `ISL`, `ISR`, `ITA`, `JAM`, `JEY`, `JOR`, `JPN`, `KAZ`, `KEN`, `KGZ`, `KHM`, `KIR`, `KNA`, `KOR`, `KWT`, `LAO`, `LBN`, `LBR`, `LBY`, `LCA`, `LIE`, `LKA`, `LSO`, `LTU`, `LUX`, `LVA`, `MAC`, `MAF`, `MAR`, `MCO`, `MDA`, `MDG`, `MDV`, `MEX`, `MHL`, `MKD`, `MLI`, `MLT`, `MMR`, `MNE`, `MNG`, `MNP`, `MOZ`, `MRT`, `MSR`, `MTQ`, `MUS`, `MWI`, `MYS`, `MYT`, `NAM`, `NCL`, `NER`, `NFK`, `NGA`, `NIC`, `NIU`, `NLD`, `NOR`, `NPL`, `NRU`, `NZL`, `OMN`, `PAK`, `PAN`, `PCN`, `PER`, `PHL`, `PLW`, `PNG`, `POL`, `PRI`, `PRK`, `PRT`, `PRY`, `PSE`, `PYF`, `QAT`, `REU`, `ROU`, `RUS`, `RWA`, `SAU`, `SDN`, `SEN`, `SGP`, `SGS`, `SHN`, `SJM`, `SLB`, `SLE`, `SLV`, `SMR`, `SOM`, `SPM`, `SRB`, `SSD`, `STP`, `SUR`, `SVK`, `SVN`, `SWE`, `SWZ`, `SXM`, `SYC`, `SYR`, `TCA`, `TCD`, `TGO`, `THA`, `TJK`, `TKL`, `TKM`, `TLS`, `TON`, `TTO`, `TUN`, `TUR`, `TUV`, `TWN`, `TZA`, `UGA`, `UKR`, `UMI`, `URY`, `USA`, `UZB`, `VAT`, `VCT`, `VEN`, `VGB`, `VIR`, `VNM`, `VUT`, `WLF`, `WSM`, `YEM`, `ZAF`, `ZMB`, `ZWE` - `address_type` (string, optional) — What kind of establishment is located at this address? - `address2` (string, optional) — Street address, line 2 - `address3` (string, optional) — Street address, line 3 (international shipping address info) - `phone` (string, optional) — Phone number associated with address ### FeedAMPReturnError - `code` (enum, required) — Code to uniquely identify the type of error - Allowed values: `MISSING_REQUIRED_FIELD`, `INVALID_CURRENCY`, `INVALID_QUANTITY`, `INVALID_REFUND_AMOUNT`, `RETURN_ALREADY_EXISTS` - `message` (string, required) — The error message for the error code - `debug` (list of map from string to any, optional) ## Examples **Request** ```json { "mp_order_number": "600A", "return_lines": [ { "mp_return_line_number": "RETURN-XX-111-FF-1111", "mp_order_line_number": "XX-111-FF-1111", "sku": "1234-12353", "quantity": 1, "currency": "USD", "requested_refund_principal": 1.1, "reason": "Wrong color sent", "preauthorized": true } ] } ``` **SDK Code** ```python import requests url = "https://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/mp_order_number/returns/mp_return_number" payload = { "mp_order_number": "600A", "return_lines": [ { "mp_return_line_number": "RETURN-XX-111-FF-1111", "mp_order_line_number": "XX-111-FF-1111", "sku": "1234-12353", "quantity": 1, "currency": "USD", "requested_refund_principal": 1.1, "reason": "Wrong color sent", "preauthorized": True } ] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.put(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/mp_order_number/returns/mp_return_number'; const options = { method: 'PUT', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"mp_order_number":"600A","return_lines":[{"mp_return_line_number":"RETURN-XX-111-FF-1111","mp_order_line_number":"XX-111-FF-1111","sku":"1234-12353","quantity":1,"currency":"USD","requested_refund_principal":1.1,"reason":"Wrong color sent","preauthorized":true}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/mp_order_number/returns/mp_return_number" payload := strings.NewReader("{\n \"mp_order_number\": \"600A\",\n \"return_lines\": [\n {\n \"mp_return_line_number\": \"RETURN-XX-111-FF-1111\",\n \"mp_order_line_number\": \"XX-111-FF-1111\",\n \"sku\": \"1234-12353\",\n \"quantity\": 1,\n \"currency\": \"USD\",\n \"requested_refund_principal\": 1.1,\n \"reason\": \"Wrong color sent\",\n \"preauthorized\": true\n }\n ]\n}") req, _ := http.NewRequest("PUT", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/mp_order_number/returns/mp_return_number") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Put.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"mp_order_number\": \"600A\",\n \"return_lines\": [\n {\n \"mp_return_line_number\": \"RETURN-XX-111-FF-1111\",\n \"mp_order_line_number\": \"XX-111-FF-1111\",\n \"sku\": \"1234-12353\",\n \"quantity\": 1,\n \"currency\": \"USD\",\n \"requested_refund_principal\": 1.1,\n \"reason\": \"Wrong color sent\",\n \"preauthorized\": true\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.put("https://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/mp_order_number/returns/mp_return_number") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"mp_order_number\": \"600A\",\n \"return_lines\": [\n {\n \"mp_return_line_number\": \"RETURN-XX-111-FF-1111\",\n \"mp_order_line_number\": \"XX-111-FF-1111\",\n \"sku\": \"1234-12353\",\n \"quantity\": 1,\n \"currency\": \"USD\",\n \"requested_refund_principal\": 1.1,\n \"reason\": \"Wrong color sent\",\n \"preauthorized\": true\n }\n ]\n}") .asString(); ``` ```php request('PUT', 'https://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/mp_order_number/returns/mp_return_number', [ 'body' => '{ "mp_order_number": "600A", "return_lines": [ { "mp_return_line_number": "RETURN-XX-111-FF-1111", "mp_order_line_number": "XX-111-FF-1111", "sku": "1234-12353", "quantity": 1, "currency": "USD", "requested_refund_principal": 1.1, "reason": "Wrong color sent", "preauthorized": true } ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/mp_order_number/returns/mp_return_number"); var request = new RestRequest(Method.PUT); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"mp_order_number\": \"600A\",\n \"return_lines\": [\n {\n \"mp_return_line_number\": \"RETURN-XX-111-FF-1111\",\n \"mp_order_line_number\": \"XX-111-FF-1111\",\n \"sku\": \"1234-12353\",\n \"quantity\": 1,\n \"currency\": \"USD\",\n \"requested_refund_principal\": 1.1,\n \"reason\": \"Wrong color sent\",\n \"preauthorized\": true\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "mp_order_number": "600A", "return_lines": [ [ "mp_return_line_number": "RETURN-XX-111-FF-1111", "mp_order_line_number": "XX-111-FF-1111", "sku": "1234-12353", "quantity": 1, "currency": "USD", "requested_refund_principal": 1.1, "reason": "Wrong color sent", "preauthorized": true ] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/mp_order_number/returns/mp_return_number")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PUT" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```