# List all return requests

Allows to get the list of return requested through the iF returns channels (e.g. returns portal). Each return request contains the list of returned items, origin address, and associated transport data. In case any parameter is sent, the last 100 returns created will be returned

Endpoint: GET /returns
Version: 1.4.3
Security: bearerAuth

## Query parameters:

  - `shop_code` (string)
    iF returns code assigned to the merchant. In case this parameter is not sent, the shop codes associated to the token will be used
    Example: "marchelacolombine"

  - `name` (string)
    Request merchant authorization (RMA) name
    Example: "R1-2944"

  - `status` (string)
    Status of the return
    Enum: "PENDING", "RECEPTION_IN_PROGRESS", "RECEPTION_COMPLETED", "RECEIVED", "CHECKED", "CLOSED", "DISCARDED", "EXPIRED", "NEEDS_VALIDATION"

  - `ecommerce_order` (string)
    Ecommerce order from where the return was requested
    Example: "2944"

  - `created_from` (string)
    Date from which the returns will be searched by creation date
    Example: "2023-04-01T12:00:00"

  - `created_to` (string)
    Date up to which the returns will be searched by creation date
    Example: "2023-04-01T13:00:00"

  - `updated_from` (string)
    Date from which the returns will be searched by update date
    Example: "2023-04-01T12:00:00"

  - `updated_to` (string)
    Date up to which the returns is to be searched by update date
    Example: "2023-04-01T13:00:00"

  - `refunded_from` (string)
    Date from which the returns will be searched by refund date
    Example: "2023-04-01T12:00:00"

  - `refunded_to` (string)
    Date up to which the returns is to be searched by refund date
    Example: "2023-04-01T13:00:00"

  - `limit` (integer)
    Number of records to obtain. Maximum value 500.
    Example: 100

  - `page` (integer)
    Page number from which the records are obtained.
    Example: 20

  - `time_zone` (string)
    Time zone used to search by date range (date_from and date_to). All date fields in the response will be formatted in this timezone. List of available values https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
    Example: "Europe/Madrid"

## Response 200 fields (application/json):

  - `returns` (array)

  - `returns.id` (string)
    Internal ID of the return order
    Example: "8e1b8c92-37a9-44c6-952a-b86bce1d8cfb"

  - `returns.shopCode` (string, required)
    Shop code which belongs the return. In case this field is not informed, it will be obtained from security context. In case it is informed, it will be validated against the security context
    Example: "marchelacolombine"

  - `returns.name` (string, required)
    Return Merchant Authorization (RMA) name
    Example: "R1-7848"

  - `returns.createdAt` (string)
    Date when the return order was created
    Example: "2022-11-17 12:01:00Z"

  - `returns.updatedAt` (string)
    Date when the return order was updated
    Example: "2022-11-17 12:01:00Z"

  - `returns.cancelledAt` (string)
    Date when the return order was updated
    Example: "2022-11-17 12:01:00Z"

  - `returns.status` (string)
    Status of the return order
    Enum: "PENDING", "RECEPTION_IN_PROGRESS", "RECEPTION_COMPLETED", "RECEIVED", "CHECKED", "CLOSED", "DISCARDED", "EXPIRED", "NEEDS_VALIDATION"

  - `returns.totalReturnFee` (number, required)
    Fee associated with the method of return
    Example: 5

  - `returns.totalReturnAmount` (number, required)
    Total amount of the all returned items
    Example: 121

  - `returns.totalTax` (number)
    Total tax of the all returned items
    Example: 21

  - `returns.totalRefund` (number)
    Total amount to be refund (totalReturnAmount - totalReturnFee)
    Example: 116

  - `returns.currency` (string, required)
    Transaction currency
    Example: "EUR"

  - `returns.customerIban` (string)
    Customer's IBAN number
    Example: "ES6821007427138154931563"

  - `returns.accountHolderName` (string)
    Name of IBAN account holder
    Example: "Mario Perez"

  - `returns.baseTotalReturnFee` (number)
    Fee associated with the method of return in shop base currency
    Example: 5

  - `returns.baseTotalReturnAmount` (number)
    Total amount of the all returned items in shop base currency
    Example: 121

  - `returns.baseTotalTax` (number)
    Total tax of the all returned items in shop base currency
    Example: 21

  - `returns.baseTotalRefund` (number)
    Total amount to be refund in shop base currency (baseTotalReturnAmount - baseTotalReturnFee)
    Example: 116

  - `returns.baseCurrency` (string)
    Shop base currency
    Example: "EUR"

  - `returns.customer` (object, required)
    Customer who is requesting the return

  - `returns.customer.fullName` (string, required)
    Full name associated to the address
    Example: "Juan Perez"

  - `returns.customer.email` (string, required)
    Email associated to the address
    Example: "customer@if.com"

  - `returns.customer.phone` (string)
    Phone associated to the address
    Example: "+34666666666"

  - `returns.customer.address` (object)

  - `returns.customer.address.line1` (string, required)
    Line 1 of the Address
    Example: "Calle de Fortunata y Jacinta 12"

  - `returns.customer.address.line2` (string)
    Line 2 data of the address

  - `returns.customer.address.city` (string, required)
    City name of the address
    Example: "Madrid"

  - `returns.customer.address.postalCode` (string, required)
    Postal code of the address
    Example: "28020"

  - `returns.customer.address.region` (string)
    Region name of the address
    Example: "Madrid"

  - `returns.customer.address.countryCode` (string, required)
    Country ISO code of the address
    Example: "ES"

  - `returns.ecommerceOrder` (object, required)
    Ecommerce order from where the return was requested

  - `returns.ecommerceOrder.id` (string, required)
    ID of the original order in the ecommerce platform
    Example: "4243234"

  - `returns.ecommerceOrder.name` (string)
    Name of the original order in the ecommerce platform
    Example: "7848"

  - `returns.ecommerceOrder.customerId` (string)
    Customer ID associated to the original order in the ecommerce platform
    Example: "23423"

  - `returns.origin` (object, required)
    Origin address for the transportation

  - `returns.origin.fullName` (string)
    Full name associated to the origin
    Example: "Juan Perez"

  - `returns.origin.email` (string)
    Email associated to the origin
    Example: "customer@if.com"

  - `returns.origin.phone` (string)
    Phone associated to the origin
    Example: "+34666666666"

  - `returns.origin.address` (object)

  - `returns.destination` (object, required)
    Destination address for the transportation

  - `returns.destination.fullName` (string)
    Full name of the destination
    Example: "iF warehouse"

  - `returns.destination.email` (string)
    Email associated to the destination
    Example: "warehouse@if.com"

  - `returns.destination.phone` (string)
    Phone associated to the destination
    Example: "+34666666666"

  - `returns.destination.address` (object)

  - `returns.returnLineItems` (array, required)
    List of returned items

  - `returns.returnLineItems.id` (string)
    Internal ID of returned item
    Example: "54048ad6-af97-417c-a8a6-7b19a154c135"

  - `returns.returnLineItems.productName` (string)
    Name of returned item
    Example: "Camisa"

  - `returns.returnLineItems.variantName` (string)
    Specific variant of the returned item
    Example: "XL Roja"

  - `returns.returnLineItems.sku` (string, required)
    SKU of the returned item
    Example: "1234567"

  - `returns.returnLineItems.barcode` (string, required)
    Barcode of the returned item
    Example: "8893892"

  - `returns.returnLineItems.vendor` (string)
    Vendor name associated to returned item
    Example: "iFreturns"

  - `returns.returnLineItems.price` (number, required)
    Price of the returned item including taxes
    Example: 141

  - `returns.returnLineItems.discount` (number)
    Discount over the original price of the returned item
    Example: 20

  - `returns.returnLineItems.paid` (number)
    Amount paid by the customer for the returned item (price - discount)
    Example: 121

  - `returns.returnLineItems.tax` (number)
    Tax of the returned item
    Example: 21

  - `returns.returnLineItems.returnAmount` (number)
    Amount to be returned to the customer
    Example: 121

  - `returns.returnLineItems.currency` (string)
    Transaction currency
    Example: "EUR"

  - `returns.returnLineItems.basePrice` (number)
    Price of the returned item including taxes in shop base currency
    Example: 141

  - `returns.returnLineItems.baseDiscount` (number)
    Discount over the original price of the returned item in shop base currency
    Example: 20

  - `returns.returnLineItems.basePaid` (number)
    Amount paid by the customer for the returned item (basePrice - baseDiscount)
    Example: 121

  - `returns.returnLineItems.baseTax` (number)
    Tax of the returned item in shop base currency
    Example: 21

  - `returns.returnLineItems.baseReturnAmount` (number)
    Amount to be returned to the customer in shop base currency
    Example: 121

  - `returns.returnLineItems.baseCurrency` (string)
    Shop base currency
    Example: "EUR"

  - `returns.returnLineItems.quantity` (number, required)
    Items units returned
    Example: 1

  - `returns.returnLineItems.imageUrl` (string)
    Url for the image of the returned item
    Example: "https://ifreturns.com/imagen/producto.jpg"

  - `returns.returnLineItems.ecommerceLineItem` (object)
    Ecommerce order line item that is returned

  - `returns.returnLineItems.ecommerceLineItem.lineItemId` (string, required)
    ID of returned line item in the original order
    Example: "8e1b8c92"

  - `returns.returnLineItems.ecommerceLineItem.productId` (string, required)
    Product ID in the ecommerce platform
    Example: "1234"

  - `returns.returnLineItems.ecommerceLineItem.variantId` (string, required)
    Variant ID in the ecommerce platform
    Example: "XS1234"

  - `returns.returnLineItems.returnReason` (object)

  - `returns.returnLineItems.returnReason.code` (string)
    Reason code why the customer returns the item
    Example: "dont-like"

  - `returns.returnLineItems.returnReason.reason` (string)
    Reason description why the customer returns the item"
    Example: "No me gusta"

  - `returns.returnLineItems.returnReason.additionalInfo` (string, required)
    Additional info about why the customer returns the item
    Example: "Presenta un fallo en la cremallera"

  - `returns.returnLineItems.refundType` (string, required)
    Refund method the customer can select for the returned item
    Enum: "ORIGINAL_PAYMENT_METHOD", "STORE_CREDIT", "EXCHANGE", "GIFT_CARD"

  - `returns.returnLineItems.refundMode` (string, required)
    Mode in which the returned item will be refunded
    Enum: "PRE_VALIDATION", "SHIPPING_COMPLETED", "SHIPPING_IN_PROGRESS", "POST_VALIDATION", "MANUAL", "INSTANT", "DROP_OFF"

  - `returns.returnLineItems.exchangeLineItems` (array)
    Information about the new product in case of exchange

  - `returns.returnLineItems.exchangeLineItems.id` (string)
    Internal ID of new item
    Example: "8e1b8c92-37a9-44c6-952a-b86bce1d8cfb"

  - `returns.returnLineItems.exchangeLineItems.productName` (string, required)
    Product ID of the new item
    Example: "Product/12345"

  - `returns.returnLineItems.exchangeLineItems.variantName` (string, required)
    Specific variant of the new item
    Example: "Blue Sweater XL Size"

  - `returns.returnLineItems.exchangeLineItems.sku` (string)
    SKU of the new item
    Example: "1234557"

  - `returns.returnLineItems.exchangeLineItems.price` (number, required)
    Price of the new item
    Example: 120

  - `returns.returnLineItems.exchangeLineItems.quantity` (number, required)
    Items units to be processed
    Example: 1

  - `returns.returnLineItems.exchangeLineItems.vendor` (string)
    Vendor name of the new item
    Example: "iFreturns"

  - `returns.returnLineItems.exchangeLineItems.ecommerceProductId` (string, required)
    Product ID in the ecommerce platform
    Example: "1234"

  - `returns.returnLineItems.exchangeLineItems.ecommerceVariantId` (string, required)
    Variant ID in the ecommerce platform
    Example: "XL1234"

  - `returns.activeTransportation` (object)
    Transport currently active to receive the returned items

  - `returns.activeTransportation.id` (string)
    Internal ID of new item
    Example: "38885822-8d44-4819-8358-345b4d83be70"

  - `returns.activeTransportation.createdAt` (string)
    Date when the Transport was created
    Example: "2022-11-17 12:05:00Z"

  - `returns.activeTransportation.status` (string)
    Status of the shipment/transport
    Enum: "REQUESTED", "PICK_UP_IN_PROGRESS", "PICK_UP_COMPLETED", "SHIPPING_IN_PROGRESS", "SHIPPING_COMPLETED", "PICK_UP_FAILED", "PICK_UP_CANCELLED", "SHIPPING_FAILED", "SHIPPING_CANCELLED"

  - `returns.activeTransportation.serviceMessage` (string)
    Name of the transport chosed by customer
    Example: "Recogida programada"

  - `returns.activeTransportation.serviceType` (string)
    Type of transport chosed by customer
    Example: "pickup"

  - `returns.activeTransportation.carrierCode` (string)
    Carrier responsible for the transport
    Example: "CORREOS-EXPRESS"

  - `returns.activeTransportation.carrierServiceCode` (string)
    Carrier service used for the transport
    Example: "correos-epaq-24"

  - `returns.activeTransportation.carrierLabel` (string)
    URL to donwload the carrier label
    Example: "https://if.com/P1R1mlc7848.pdf"

  - `returns.activeTransportation.carrierTrackingUrl` (string)
    URL for tracking the shipment
    Example: "https://if.com/tracking/3230006199506927"

  - `returns.activeTransportation.carrierPickupReference` (string)
    Pickup code generated by the carrier
    Example: "125172899"

  - `returns.activeTransportation.carrierReference` (string)
    Transport code generated by the carrier
    Example: "3230006199506927"

  - `returns.activeTransportation.clientReference` (string)
    Internal code generated for the transport
    Example: "P1R1mlc7848"

  - `returns.activeTransportation.pickupDate` (string)
    Date when the return order will be picked up. Only available in case of pickup return method
    Example: "2022-11-22"

  - `pageInfo` (object)

  - `pageInfo.totalRecords` (integer)
    Total number of records meet search criteria
    Example: 351

  - `pageInfo.totalPages` (integer)
    Number of pages comprising all available records. It is calculated based on the limit value
    Example: 4


## Response 400 fields

## Response 401 fields

## Response 404 fields

## Response 500 fields