For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
DocsAPI ReferenceChangelog
DocsAPI ReferenceChangelog
  • REST
    • Authentication
    • Platform
    • Event-Driven Sync (EDRTS)
    • Content
    • FeedAMP Order
    • FeedAMP Order V2
          • GETGet returns filtered by search parameters
          • GETGet an individual return
          • POSTRun an operation on an return
    • FeedAMP Order Source
LogoLogo
RESTFeedAMP Order V2Returns

Get returns filtered by search parameters

GET
https://api.feedamp.feedonomics.com/api/v2/returns
GET
/api/v2/returns
$curl https://api.feedamp.feedonomics.com/api/v2/returns \
>     -H "token: token" \
>     -H "client: 1" \
>     -u "<username>:<password>"
1{
2  "returns": [
3    {
4      "id": "109872189273617283",
5      "marketplace_return_number": "111-99998888-55555",
6      "imported_date": {},
7      "return_lines": [
8        {
9          "id": "109872189273617283",
10          "marketplace_return_line_number": "XX-111-FF-1111",
11          "marketplace_order_line_number": "XX-111-FF-1111",
12          "feedamp_order_line_id": "109872189273617283",
13          "sku": "1234-12353",
14          "product_name": "ACME Super Product",
15          "quantity": 1,
16          "unit_price": 200,
17          "reason": "Not what I ordered",
18          "original_price": 1.95,
19          "requested_refund": 1.95,
20          "shipping_expected": false,
21          "destination": "string",
22          "label_cost": 1.95,
23          "tracking_info": {
24            "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'",
25            "tracking_number": "string"
26          }
27        }
28      ],
29      "order_id": "109872189273617283",
30      "integration_name": "My Store",
31      "marketplace_name": "Target",
32      "rma": "1234567890",
33      "merchant_return_number": "1234567890",
34      "marketplace_order_number": "000-1234567-7654321",
35      "marketplace_state": "Shipped",
36      "normalized_marketplace_state": "string",
37      "pre_authorized": true,
38      "customer": {
39        "full_name": "A. Customer",
40        "email": "customer@internet-provider.com",
41        "phone": "5558675309",
42        "vat": "78131452263"
43      },
44      "request_date": {},
45      "respond_by_date": {},
46      "notes": "leave by the back door.",
47      "shipping_address": {
48        "full_name": "John M. Doe",
49        "address1": "123 Fake Street",
50        "city": "Ghost Town",
51        "state": "DC",
52        "postal_code": "91234",
53        "country_code": "USA",
54        "address_type": "business",
55        "address2": "Building 456",
56        "address3": "Room 789",
57        "country_code_iso2": "US",
58        "phone": "9997776666"
59      },
60      "return_type": "SHIP"
61    }
62  ],
63  "next_cursor": "string"
64}
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.
Was this page helpful?
Previous

Apply a refund on an return

Next

Get an individual return

Built with

Authentication

AuthorizationBasic

Basic authentication of the form Basic <base64(username:password)>.

Headers

tokenstringRequired

The Authentication token obtained from the v1 get_token route

clientintegerRequired
The ID of the client making the request

Query parameters

marketplace_statestringOptional

The state of the return. Multiple states can be matched by specifying a comma-separated list of values.

marketplace_state_changed_afterdatetimeOptional

Marketplace state was last changed after this datetime. RFC-3339 date-time format — fractional seconds not allowed

marketplace_state_changed_beforedatetimeOptional

Marketplace state was last changed before this datetime. RFC-3339 date-time format — fractional seconds not allowed

imported_afterdatetimeOptional

Returns created in FeedAMP after this datetime. RFC-3339 date-time format — fractional seconds not allowed

imported_beforedatetimeOptional

Returns created in FeedAMP before this datetime. RFC-3339 date-time format — fractional seconds not allowed

normalized_marketplace_stateenumOptional
FeedAMP's interpretation of the marketplace state <ul> <li>PENDING_AUTHORIZATION - Return where the sales channel is awaiting authorization from the seller to approve the return request. Not used by all channels.</li> <li>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.</li> <li>CONFIRMED - Indicates that action that caused the return to be in PENDING_CONFIRMATION has been completed. Not used by all channels.</li> <li>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.</li> <li>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</li> <li>CANCELLED - The return has been cancelled and no further action is required.</li> <li>COMPLETE - The return is recognized as being complete by the channel.</li> </ul>
idstringOptional

FeedAMP return ID. May be a comma-delimited list of multiple IDs.

marketplace_return_numberstringOptional

The primary return ID provided by the marketplace. May be a comma-delimited list of multiple values.

rmastringOptional

RMA ID of a return. May be a comma-delimited list of multiple values.

customer_order_numberstringOptional

The customer-facing order number associated with this return. May be a comma-delimited list of multiple values.

return_typeenumOptional
Filter returns by the return type
Allowed values:
integration_idstringOptional
FeedAMP integration ID to limit results to a single integration
limitintegerOptional1-250Defaults to 100
The max number of records in the response
cursorstringOptional
Cursor for the next page of records
include_orderbooleanOptional
Include the order data, associated with the return, in response

Response

List of returns
returnslist of objects
next_cursorstring

Errors

400
Bad Request Error
401
Unauthorized Error
500
Internal Server Error
503
Service Unavailable Error
FeedAMP’s interpretation of the marketplace state <ul>
  • 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.
    • </ul>