> 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. # Search returns GET https://api.feedamp.feedonomics.com/api/v1/returns Search returns for a client. Filter results via query params. The maximum recommended call frequency for retrieving data from this endpoint is 2 requests per second. Reference: https://docs.feedonomics.com/developer/api-reference/rest/feedamp-order-api-v1/customer-initiated-returns/get-returns ## Authentication - `token` header (required) — The Authentication token obtained from the get_token route. - `x-api-key` header (required) — The SSO token obtained from the Feedonomics platform SSO token route. ## Request ### Query parameters - `open` (boolean, optional) — Setting to true will limit results to Returns considered to be in an open state. Setting to false will produce closed state Returns. Open Returns are Returns that are NOT in a terminal state. Terminal states are considered to be `Merchant Refunded`, `Merchant Rejected`, or `Customer Cancelled`. NOTE: This parameter is overridden by the "state" parameter if provided - `state` (list of enum, optional) — Comma delimited list of Return states to filter by. _e.g: ?state=Pending Authorization,Pending Confirmation_ - Allowed values: `Pending Authorization`, `Pending Confirmation`, `Pending Shipping`, `Pending Refund`, `Processing Refund`, `Merchant Refunded`, `Merchant Rejected`, `Customer Cancelled` - `marketplaces` (string, optional) — comma delimited list of marketplace IDs to filter results by - `created-before` (datetime, optional) — filter results by returns created before date-time (ISO 8601) | if timezone is not specified default is EST/EDT. - `created-after` (datetime, optional) — filter results by returns created after date-time (ISO 8601) | if timezone is not specified default is EST/EDT. - `refreshed-before` (datetime, optional) — filter results by returns refreshed before date-time (ISO 8601) | if timezone is not specified default is EST/EDT. - `refreshed-after` (datetime, optional) — filter results by returns refreshed after date-time (ISO 8601) | if timezone is not specified default is EST/EDT. - `merchant-return-number` (string, optional) — filter results by merchant return number (RMA) - `limit` (double, optional) — THe max number of returns in the response (50-200). Default is 100. - `cursor` (string, optional) — Cursor for the next page of returns. ### Headers - `client` (integer, required) — The id of the client making the request. ## Response ### 200 List of Order Returns - `returns` (list of Return, optional) - `next_cursor` (string, optional) — The cursor to get the next page of returns. ## Errors ### 400 Bad Request Error Invalid request - `message` (string, optional) ## Types ### Return - `id` (string, required) — FeedAMP unique return id, used for other calls as return-d - `state` (string, required) — The state of the return - `integration_name` (string, required) — The name of the marketplace integration you have on FeedAMP - `paused` (integer, required) — 1 if this return has been paused on FeedAMP side, 0 if not - `return_info` (ReturnReturnInfo, required) - `order_id` (string, optional) — FeedAMP unique order id to which the return belongs. ### ReturnReturnInfo - `mp_return_number` (string, required) — The primary return number provided by the marketplace. - `mp_order_number` (string, required) — The marketplace order number related to the return. - `pre_authorized` (double, required) — 1 if the return has been pre-authorized by the marketplace. - `request_date` (string, required) — The date the return was originally requested by the customer. - `return_lines` (list of ReturnReturnInfoReturnLinesItems, required) — List of order lines being returned. Each return line has its own number as well. - `respond_by_date` (string, optional) — The due date required to respond to the marketplace with resolution. - `notes` (string, optional) — Free-text notes from the return, usually from the customer. - `merchant_return_number` (string, optional) — Return Number (or RMA) provided by the seller ### ReturnReturnInfoReturnLinesItems - `mp_return_line_number` (string, required) — Marketplace number for this return line - `mp_order_line_number` (string, required) — The marketplace's order line that is being returned in this return line. - `quantity` (double, required) — Number of items being returned in this line. - `reason` (enum, required) — Reason reported by customer for the returned item. - Allowed values: `accidental_order`, `wrong_item_received`, `defective_item_received`, `damaged_item_received`, `item_never_received`, `item_received_late`, `wrong_quantity_received`, `other` - `shipping_expected` (double, required) — 1 if the item is going to be shipped back to the seller. 0 if the item is not required to be shipped back to the seller. - `sku` (string, optional) — The SKU of the product that was included in the marketplace listing. - `product_name` (string, optional) — The product title, as displayed in the marketplace listing. - `requested_refund_principal` (double, optional) — The requested refund to the principal (base item price). - `requested_refund_tax` (double, optional) — The requested refund to the tax amount. - `requested_refund_shipping` (double, optional) — The requested refund to the shipping amount. - `requested_refund_shipping_tax` (double, optional) — The requested refund to the shipping tax. - `carrier` (string, optional) — Carrier for the return shipment. - `tracking_number` (string, optional) — Tracking number for the return shipment. - `destination` (string, optional) — Return address for shipment, or warehouse identifier. ## Examples **Response** ```json { "returns": [ { "id": "123", "state": "Pending Authorization", "integration_name": "amazon", "paused": 0, "return_info": { "mp_return_number": "152-123344ABC", "mp_order_number": "111-99998888-55555", "pre_authorized": 1, "request_date": "2018-02-07T22:00:00.000Z", "return_lines": [ { "mp_return_line_number": "123-456-789", "mp_order_line_number": "afdafasdgasdg", "quantity": 2, "reason": "wrong_item_received", "shipping_expected": 1, "sku": "1234-12353", "product_name": "Beats Pill Speakers", "requested_refund_principal": 1.05, "requested_refund_tax": 0.11, "requested_refund_shipping": 0, "requested_refund_shipping_tax": 0, "carrier": "FedEx", "tracking_number": "168739720393", "destination": "123 Example St. Los Angeles, CA" } ], "respond_by_date": "2018-02-09T22:00:00.000Z", "notes": "Didn't fit me!", "merchant_return_number": "RMA-1234" }, "order_id": "456" } ], "next_cursor": "12FDG-31dsfgHW" } ``` **SDK Code** ```python import requests url = "https://api.feedamp.feedonomics.com/api/v1/returns" querystring = {"state":"Pending Authorization,Pending Confirmation,Pending Shipping,Pending Refund,Processing Refund"} headers = { "client": "1", "token": "" } response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.feedamp.feedonomics.com/api/v1/returns?state=Pending+Authorization%2CPending+Confirmation%2CPending+Shipping%2CPending+Refund%2CProcessing+Refund'; const options = {method: 'GET', headers: {client: '1', token: ''}}; 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" "net/http" "io" ) func main() { url := "https://api.feedamp.feedonomics.com/api/v1/returns?state=Pending+Authorization%2CPending+Confirmation%2CPending+Shipping%2CPending+Refund%2CProcessing+Refund" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("client", "1") req.Header.Add("token", "") 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://api.feedamp.feedonomics.com/api/v1/returns?state=Pending+Authorization%2CPending+Confirmation%2CPending+Shipping%2CPending+Refund%2CProcessing+Refund") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["client"] = '1' request["token"] = '' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.feedamp.feedonomics.com/api/v1/returns?state=Pending+Authorization%2CPending+Confirmation%2CPending+Shipping%2CPending+Refund%2CProcessing+Refund") .header("client", "1") .header("token", "") .asString(); ``` ```php request('GET', 'https://api.feedamp.feedonomics.com/api/v1/returns?state=Pending+Authorization%2CPending+Confirmation%2CPending+Shipping%2CPending+Refund%2CProcessing+Refund', [ 'headers' => [ 'client' => '1', 'token' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.feedamp.feedonomics.com/api/v1/returns?state=Pending+Authorization%2CPending+Confirmation%2CPending+Shipping%2CPending+Refund%2CProcessing+Refund"); var request = new RestRequest(Method.GET); request.AddHeader("client", "1"); request.AddHeader("token", ""); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "client": "1", "token": "" ] let request = NSMutableURLRequest(url: NSURL(string: "https://api.feedamp.feedonomics.com/api/v1/returns?state=Pending+Authorization%2CPending+Confirmation%2CPending+Shipping%2CPending+Refund%2CProcessing+Refund")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers 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() ```