> 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 for an order

GET https://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/{mp_order_number}/returns

Get all seller-initiated refunds for an order

Reference: https://docs.feedonomics.com/developer/api-reference/rest/feed-amp-order-source-api/returns/get-order-returns

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, 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

## Response

### 200

Get Return

- `returns` (list of FeedAMPReturnModel, required)
- `next_cursor` (string, optional) — The cursor to get the next page of orders

## 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

### FeedAMPReturnModel

Return Model

- `status` (enum, optional) — the return authorization number generated by the seller.
  - Allowed values: `AUTHORIZED`, `REFUNDED`, `COMPLETED`
- `rma` (string, optional) — The return authorization number generated by the seller. This field is read-only for the marketplace.
- `mp_return_number` (string, optional) — the mp return number
- `mp_order_number` (string, optional) — the mp order number associated with the return
- `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)&#x20;
  - Allowed values: `SHIP`, `IN_STORE`, `NO_RETURN`
- `return_lines` (list of ReturnLine, optional)
- `merchant_refund_lines` (list of ReturnLineRefund, optional)
- `errors` (list of ReturnError, optional) — Any unresolved errors reported by the marketplace for this return

### 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)

### 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

### 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&#x20; 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

### ReturnLineRefund

The refund amounts approved by the seller

- `mp_return_line_number` (string, required) — The marketplace identifier of this unique return line
- `principal_refund_amount` (double, optional) — The amount of the requested return principal that has been approved
- `shipping_refund_amount` (double, optional) — The amount of the requested shipping amount that has been approved

### ReturnError

An object detailing the validation errors encountered in the marketplace

- `code` (enum, required) — Code to uniquely identify the type of error
  - Allowed values: `EXCESS_REFUND`, `FULL_REFUND_REQUIRED`, `INVALID_CURRENCY`, `INVALID_ITEM_REFUND`, `INVALID_INVALID_ITEM_TAX_REFUND`, `INVALID_QUANTITY`, `INVALID_SHIPPING`, `MP_LINE_NUMBER_DOES_NOT_EXIST`
- `message` (string, required) — The error message for the error code

## Examples

**Response**

```json
{
  "returns": [
    {
      "status": "AUTHORIZED",
      "rma": "RMA-12345",
      "mp_return_number": "RET-600A",
      "mp_order_number": "600A",
      "request_date": {},
      "respond_date": {},
      "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",
        "phone": "9997776666"
      },
      "customer_email": "customer@internet-provider.com",
      "return_type": "SHIP",
      "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,
          "product_name": "ACME Super Product",
          "unit_price": 1.1,
          "tax": 1.1,
          "requested_refund_tax": 1.1,
          "carrier": "UPS",
          "tracking_number": "XXX-DDD-XXXX-DDDD"
        }
      ],
      "merchant_refund_lines": [
        {
          "mp_return_line_number": "RETURN-XX-111-FF-1111",
          "principal_refund_amount": 1.1,
          "shipping_refund_amount": 1.1
        }
      ],
      "errors": [
        {
          "code": "EXCESS_REFUND",
          "message": "Requested refund amount for line exceeds line cost"
        }
      ]
    }
  ],
  "next_cursor": "12FDG-31dsfgHW"
}
```

**SDK Code**

```python
import requests

url = "https://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/mp_order_number/returns"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/mp_order_number/returns';
const options = {method: 'GET', headers: {Authorization: 'Bearer <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://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/mp_order_number/returns"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <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://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/mp_order_number/returns")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/mp_order_number/returns")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/mp_order_number/returns', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/mp_order_number/returns");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://marketplace-order-api.feedamp.feedonomics.com/api/v1/orders/mp_order_number/returns")! 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()
```