> 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. # Get returns filtered by search parameters GET https://api.feedamp.feedonomics.com/api/v2/returns Get all returns that match the parameters that you have submitted. 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/feed-amp-order-api-v2/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 - `marketplace_state` (string, optional) — The state of the return. Multiple states can be matched by specifying a comma-separated list of values. - `marketplace_state_changed_after` (datetime, optional) — Marketplace state was last changed after this datetime. RFC-3339 date-time format — fractional seconds not allowed - `marketplace_state_changed_before` (datetime, optional) — Marketplace state was last changed before this datetime. RFC-3339 date-time format — fractional seconds not allowed - `imported_after` (datetime, optional) — Returns created in FeedAMP after this datetime. RFC-3339 date-time format — fractional seconds not allowed - `imported_before` (datetime, optional) — Returns created in FeedAMP before this datetime. RFC-3339 date-time format — fractional seconds not allowed - `normalized_marketplace_state` (enum, optional) — FeedAMP's interpretation of the marketplace state PENDING\_AUTHORIZATION - Return where the sales channel is awaiting authorization from the seller to approve the return request. Not used by all channels. PENDING\_CONFIRMATION - Used to denote that the return is awaiting confirmation of an event, initiated by the seller or customer. For example, if the customer is returning items to the seller, the return will remain in this state until the seller confirms the receipt and condition of the items. If the items are being returned to the channel, the return may stay in this state until the package is scanned in by the carrier. Not used by all channels. CONFIRMED - Indicates that action that caused the return to be in PENDING\_CONFIRMATION has been completed. Not used by all channels. PENDING\_REFUND - The channel is awaiting the seller to submit the amount to be refunded. For example, the channel may allow a restocking fee, so an amount lower than what was requested may be refunded. Not used by all channels. UNKNOWN - Indicates that the return's marketplace\_state is not recognized by FeedAMP. This usually indicates that the return requires manual intervention by the seller through the channel's portal CANCELLED - The return has been cancelled and no further action is required. COMPLETE - The return is recognized as being complete by the channel. - Allowed values: `PENDING_AUTHORIZATION`, `PENDING_CONFIRMATION`, `PENDING_REFUND`, `CONFIRMED`, `REJECTED`, `UNKNOWN`, `CANCELLED`, `COMPLETE` - `id` (string, optional) — FeedAMP return ID. May be a comma-delimited list of multiple IDs. - `marketplace_return_number` (string, optional) — The primary return ID provided by the marketplace. May be a comma-delimited list of multiple values. - `rma` (string, optional) — RMA ID of a return. May be a comma-delimited list of multiple values. - `customer_order_number` (string, optional) — The customer-facing order number associated with this return. May be a comma-delimited list of multiple values. - `return_type` (enum, optional) — Filter returns by the return type - Allowed values: `SHIP`, `IN_STORE`, `NO_RETURN` - `integration_id` (string, optional) — FeedAMP integration ID to limit results to a single integration - `limit` (integer, optional, default: 100) — The max number of records in the response - `cursor` (string, optional) — Cursor for the next page of records - `include_order` (boolean, optional) — Include the order data, associated with the return, in response ### Headers - `client` (integer, required) — The ID of the client making the request ## Response ### 200 List of returns - `returns` (list of Return, required) - `next_cursor` (string, optional) ## Errors ### 400 Bad Request Error Validation error(s) on requested filter parameters - `list of ReturnsGetResponsesContentApplicationJsonSchemaItems` ### 401 Unauthorized Error Error validating credentials or access to resources. - `error` (string, required) ### 500 Internal Server Error An unexpected server error occurred. Please contact Feedonomics Support if error persists. - `error` (string, required) ### 503 Service Unavailable Error Server is temporarily unable to handle the request - `error` (string, required) ## Types ### Return Model representing a customer return of one or more order items - `id` (string, required) — Unique identifier for a record - `marketplace_return_number` (string, required) — The primary return number used to identify the return in the marketplace's system - `imported_date` (datetime, required) — The datetime at which the order was first seen by FeedAMP. RFC-3339 format 2020-12-31T12:34:56-05:00 - `return_lines` (list of ReturnLine, required) — A collection of ReturnLine objects. - `order_id` (string, optional) — Identifier for the order this return is for, if applicable - `integration_name` (string, optional) — Client-configured identifier for the integration from which the order originated - `marketplace_name` (string, optional) — The platform from which the order originated - `rma` (string, optional) — RMA ID of the return - `merchant_return_number` (string, optional) — Return identifier provided by the merchant, separately from RMA - `marketplace_order_number` (string, optional) — Order number of the order associated with this return - `marketplace_state` (string, optional) — The marketplace's own representation of the return state - `normalized_marketplace_state` (string, optional) — FeedAMP's interpretation of the marketplace state - `pre_authorized` (boolean, optional) — Whether customer returns are assumed to be authorized by the merchant - `marketplace_fulfilled` (boolean, optional) — Whether the merchant handles processing and refunding the return (no seller involvement) - `customer` (Customer, optional) - `request_date` (datetime, optional) — Date the customer initiated the return. RFC-3339 format 2020-12-31T12:34:56-05:00 - `respond_by_date` (datetime, optional) — Date by which the seller must respond to the return request. RFC-3339 format 2020-12-31T12:34:56-05:00 - `notes` (string, optional) — The customer's notes about the return. - `shipping_address` (StreetAddress, optional) — Customer's Shipping Information - `return_type` (enum, optional) - Allowed values: `SHIP`, `IN_STORE`, `NO_RETURN` ### ReturnsGetResponsesContentApplicationJsonSchemaItems - `query_parameter` (string, required) — The query parameter that did not pass validation - `message` (string, required) — Message describing the error ### ReturnLine An object representing a line in an order - `id` (string, required) — Unique identifier for a record - `marketplace_return_line_number` (string, optional) — The marketplace identifier of this unique return line - `marketplace_order_line_number` (string, optional) — The associated order line for the item being returned - `feedamp_order_line_id` (string, optional) — Unique identifier for a record - `sku` (string, optional) — The SKU of the marketplace product represented by this return line - `product_name` (string, optional) — The product title, as displayed in the marketplace listing - `quantity` (integer, optional) — The amount of product being returned - `unit_price` (double, optional) — The price for a single (1) quantity of product (not including tax, shipping, or discounts) - `reason` (string, optional) — Return reason provided by the customer - `original_price` (double, optional) — Original purchase price for the returned item - `requested_refund` (double, optional) — Requested refund amount for the returned item - `shipping_expected` (boolean, optional) — Whether merchant should expect to receive the item back from the customer - `destination` (string, optional) — Destination - `label_cost` (double, optional) — Cost of return shipping - `tracking_info` (TrackingInfo, optional) — If the returned item(s) are being shipped back by the customer, the field will contain tracking information. If the items are to be returned to the store, the field will be null - `condition` (string, optional) — For marketplace_fulfilled returns, the condition of the returned item ### Customer - `full_name` (string, optional) — The full name of the customer - `email` (string, optional) — The customer's email address - `phone` (string, optional) — The phone number of the customer - `vat` (string, optional) — International Value-Added Tax identification number of customer ### StreetAddress Customer's Shipping Information - `full_name` (string, required) — Primary name on the shipping address - `address1` (string, required) — Shipping street address, line 1 - `city` (string, required) — Shipping address (City) - `state` (string, required) — Shipping address (State or Province) - `postal_code` (string, required) — Shipping 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) — The category of the shipping address - `address2` (string, optional) — Shipping street address, line 2 - `address3` (string, optional) — Shipping street address, line 3 (international shipping address info) - `country_code_iso2` (enum, optional) — ISO 3166-1 alpha-2 country codes - Allowed values: `AD`, `AE`, `AF`, `AG`, `AI`, `AL`, `AM`, `AO`, `AQ`, `AR`, `AS`, `AT`, `AU`, `AW`, `AX`, `AZ`, `BA`, `BB`, `BD`, `BE`, `BF`, `BG`, `BH`, `BI`, `BJ`, `BL`, `BM`, `BN`, `BO`, `BQ`, `BR`, `BS`, `BT`, `BV`, `BW`, `BY`, `BZ`, `CA`, `CC`, `CD`, `CF`, `CG`, `CH`, `CI`, `CK`, `CL`, `CM`, `CN`, `CO`, `CR`, `CU`, `CV`, `CW`, `CX`, `CY`, `CZ`, `DE`, `DJ`, `DK`, `DM`, `DO`, `DZ`, `EC`, `EE`, `EG`, `EH`, `ER`, `ES`, `ET`, `FI`, `FJ`, `FK`, `FM`, `FO`, `FR`, `GA`, `GB`, `GD`, `GE`, `GF`, `GG`, `GH`, `GI`, `GL`, `GM`, `GN`, `GP`, `GQ`, `GR`, `GS`, `GT`, `GU`, `GW`, `GY`, `HK`, `HM`, `HN`, `HR`, `HT`, `HU`, `ID`, `IE`, `IL`, `IM`, `IN`, `IO`, `IQ`, `IR`, `IS`, `IT`, `JE`, `JM`, `JO`, `JP`, `KE`, `KG`, `KH`, `KI`, `KM`, `KN`, `KP`, `KR`, `KW`, `KY`, `KZ`, `LA`, `LB`, `LC`, `LI`, `LK`, `LR`, `LS`, `LT`, `LU`, `LV`, `LY`, `MA`, `MC`, `MD`, `ME`, `MF`, `MG`, `MH`, `MK`, `ML`, `MM`, `MN`, `MO`, `MP`, `MQ`, `MR`, `MS`, `MT`, `MU`, `MV`, `MW`, `MX`, `MY`, `MZ`, `NA`, `NC`, `NE`, `NF`, `NG`, `NI`, `NL`, `NO`, `NP`, `NR`, `NU`, `NZ`, `OM`, `PA`, `PE`, `PF`, `PG`, `PH`, `PK`, `PL`, `PM`, `PN`, `PR`, `PS`, `PT`, `PW`, `PY`, `QA`, `RE`, `RO`, `RS`, `RU`, `RW`, `SA`, `SB`, `SC`, `SD`, `SE`, `SG`, `SH`, `SI`, `SJ`, `SK`, `SL`, `SM`, `SN`, `SO`, `SR`, `SS`, `ST`, `SV`, `SX`, `SY`, `SZ`, `TC`, `TD`, `TF`, `TG`, `TH`, `TJ`, `TK`, `TL`, `TM`, `TN`, `TO`, `TR`, `TT`, `TV`, `TW`, `TZ`, `UA`, `UG`, `UM`, `US`, `UY`, `UZ`, `VA`, `VC`, `VE`, `VG`, `VI`, `VN`, `VU`, `WF`, `WS`, `XK`, `YE`, `YT`, `ZA`, `ZM`, `ZW` - `phone` (string, optional) — Shipping phone number ### TrackingInfo If the returned item(s) are being shipped back by the customer, the field will contain tracking information. If the items are to be returned to the store, the field will be null - `carrier` (string, optional) — Carrier used by seller for shipping. Any string will be accepted, see examples for preferred spellings of common carriers. - `tracking_number` (string, optional) — Tracking number provided by Carrier for the shipment ## Examples **Response** ```json { "returns": [ { "id": "109872189273617283", "marketplace_return_number": "111-99998888-55555", "imported_date": {}, "return_lines": [ { "id": "109872189273617283", "marketplace_return_line_number": "XX-111-FF-1111", "marketplace_order_line_number": "XX-111-FF-1111", "feedamp_order_line_id": "109872189273617283", "sku": "1234-12353", "product_name": "ACME Super Product", "quantity": 1, "unit_price": 200, "reason": "Not what I ordered", "original_price": 1.95, "requested_refund": 1.95, "shipping_expected": false, "destination": "string", "label_cost": 1.95, "tracking_info": { "carrier": " '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" }, "condition": "SELLABLE" } ], "order_id": "109872189273617283", "integration_name": "My Store", "marketplace_name": "Target", "rma": "1234567890", "merchant_return_number": "1234567890", "marketplace_order_number": "000-1234567-7654321", "marketplace_state": "Shipped", "normalized_marketplace_state": "string", "pre_authorized": true, "marketplace_fulfilled": true, "customer": { "full_name": "A. Customer", "email": "customer@internet-provider.com", "phone": "5558675309", "vat": "78131452263" }, "request_date": {}, "respond_by_date": {}, "notes": "leave by the back door.", "shipping_address": { "full_name": "John M. Doe", "address1": "123 Fake Street", "city": "Ghost Town", "state": "DC", "postal_code": "91234", "country_code": "USA", "address_type": "business", "address2": "Building 456", "address3": "Room 789", "country_code_iso2": "US", "phone": "9997776666" }, "return_type": "SHIP" } ], "next_cursor": "string" } ``` **SDK Code** ```python import requests url = "https://api.feedamp.feedonomics.com/api/v2/returns" querystring = {"imported_after":"2024-03-13T08:50:59-08:00","imported_before":"2024-03-13T08:50:59-08:00","integration_id":"109872189273617283","marketplace_state_changed_after":"2024-03-13T08:50:59-08:00","marketplace_state_changed_before":"2024-03-13T08:50:59-08:00"} headers = { "client": "1", "token": "" } response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.feedamp.feedonomics.com/api/v2/returns?imported_after=2024-03-13T08%3A50%3A59-08%3A00&imported_before=2024-03-13T08%3A50%3A59-08%3A00&integration_id=109872189273617283&marketplace_state_changed_after=2024-03-13T08%3A50%3A59-08%3A00&marketplace_state_changed_before=2024-03-13T08%3A50%3A59-08%3A00'; 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/v2/returns?imported_after=2024-03-13T08%3A50%3A59-08%3A00&imported_before=2024-03-13T08%3A50%3A59-08%3A00&integration_id=109872189273617283&marketplace_state_changed_after=2024-03-13T08%3A50%3A59-08%3A00&marketplace_state_changed_before=2024-03-13T08%3A50%3A59-08%3A00" 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/v2/returns?imported_after=2024-03-13T08%3A50%3A59-08%3A00&imported_before=2024-03-13T08%3A50%3A59-08%3A00&integration_id=109872189273617283&marketplace_state_changed_after=2024-03-13T08%3A50%3A59-08%3A00&marketplace_state_changed_before=2024-03-13T08%3A50%3A59-08%3A00") 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/v2/returns?imported_after=2024-03-13T08%3A50%3A59-08%3A00&imported_before=2024-03-13T08%3A50%3A59-08%3A00&integration_id=109872189273617283&marketplace_state_changed_after=2024-03-13T08%3A50%3A59-08%3A00&marketplace_state_changed_before=2024-03-13T08%3A50%3A59-08%3A00") .header("client", "1") .header("token", "") .asString(); ``` ```php request('GET', 'https://api.feedamp.feedonomics.com/api/v2/returns?imported_after=2024-03-13T08%3A50%3A59-08%3A00&imported_before=2024-03-13T08%3A50%3A59-08%3A00&integration_id=109872189273617283&marketplace_state_changed_after=2024-03-13T08%3A50%3A59-08%3A00&marketplace_state_changed_before=2024-03-13T08%3A50%3A59-08%3A00', [ 'headers' => [ 'client' => '1', 'token' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.feedamp.feedonomics.com/api/v2/returns?imported_after=2024-03-13T08%3A50%3A59-08%3A00&imported_before=2024-03-13T08%3A50%3A59-08%3A00&integration_id=109872189273617283&marketplace_state_changed_after=2024-03-13T08%3A50%3A59-08%3A00&marketplace_state_changed_before=2024-03-13T08%3A50%3A59-08%3A00"); 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/v2/returns?imported_after=2024-03-13T08%3A50%3A59-08%3A00&imported_before=2024-03-13T08%3A50%3A59-08%3A00&integration_id=109872189273617283&marketplace_state_changed_after=2024-03-13T08%3A50%3A59-08%3A00&marketplace_state_changed_before=2024-03-13T08%3A50%3A59-08%3A00")! 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() ```