/returns (version 1)

Name

/returns

Method

GET

Request

Name	Type	Mandatory	Description
api_token	string	yes	API key provided by SWAP.
store	string	yes	The store id that the RMAs belong to.
from_date	date	yes	Only orders that were created or modified on or after this date will be returned.
to_date	date	no	Only orders that were modified before or on this date will be returned.
limit	number	yes	The number of orders to return (max is 50). This means the list of orders will be paginated if there are more than 50 that fulfil the request parameters.
version	number	yes	1

Response

The endpoint will return a JSON payload with 3 levels:

Root level
- Orders level
  - billing_address (Billing Address Information object)
  - Products level (products belonging to the order)

Root level

Name	Type	Description
from_date	date	The same from_date value sent in the request.
to_date	date	The same to_date value sent in the request.
next_from_date	date	This is the from_date of the last order returned in the orders field (orders are sorted by "date modified" in asc order). Pagination is achieved by sending this value in the from_date in the request.
limit	number	The same limit value sent in the request.
returned	number	The number of orders returned in this response.
remaining	number	Number of orders remaining that fulfill the request parameters.
orders	list of orders	The list of orders that fulfill the request parameters.
version	number	1

Orders level

Name	Type	Description
order_name	string	Shopify's order name
order_id	string	Shopify's order ID
rma	string	SWAP's RMA number
date_created	date	Date the return was created
date_updated	date	Date the return was updated
type_string	string	A comma separated string containing the types of returns.
type	list of strings	An array listing the types of returns. Can be one of the following: - Refund - Shop Now Credit - Shop Later Credit - Additional Payment - Recycle - Warranty
shipping_status	string	The shipping status. Possible values: - Pre-Transit - In-Transit - Delivered
status	string	The status of the return. Possible values are: - Open - Needs Review - Closed - Expired - On Hold - Cancelled
total	number	Total amount of the return
return_id	string	SWAP's internal return id
shop_now_revenue	number	The revenue of orders that include type "Shop Now Credit"
shop_later_revenue	number	The revenue of orders that include type "Shop Later Credit"
exchange_revenue	number	The revenue of orders that include type "Exchange"
refund_revenue	number	The revenue of orders that include type "Refund"
store_id	string	SWAP's internal store id
total_additional_payment	number	If there was an additional payment involved, this shows the total amount
total_credit_exchange_value	number	Total value of the exchange value
total_refund_value_customer_currency	number	Total value of the refund value
store_name	string	The name of the store
customer_currency	string	The currency that the customer used to pay
customer_name	string	The name of the customer
screen_type	string	Can be "Desktop" or "Mobile"
customer_locale	string	The language locale used by the customer
shipping_carrier	string	The carrier in charge of the shipment
shopify_order_date	date	The date the order was created in Shopify
shipment_from_address_country	string	Country where the shipment is shipped from
shipment_from_address_city	string	City where the shipment is shipped from
shipment_from_address_parcel_weight	number	Weight of the parcel (in grams)
shipment_from_address_state	string	State where the shipment is shipped from
tags	string	Order tags
billing_address	object	Billing address information
processed_by	string	Name of the agent that processed the return
order_alt_type	string	Used to designate a different use case/type for a returnOrder outside of a normal return RMA (Recycle, refurbishment, etc.)
total_recycle_credit	number	Credit earned from recycling
num_recycled_products	number	Total number of the recycled products
total_weight_recycle_products	number	Total weight of the recycled products
quality_control_status	string	Pass if condition of all products is Sellable. Fail otherwise.
delivered_date	date	Date the return order was delivered.
elapsed_days_purchase_to_return	number	Days between order created and return requested
elapsed_days_return_to_delivery	number	Days between return requested and return delivered
elapsed_days_delivery_closed	number	Days between the return being delivered and the return being closed.
date_closed	date	Date that the return was closed
tracking_number	string	The return’s tracking number
products	list of products	The list of products whose "productActionType" equals to Return.

billing_address object

Name	Type	Description
name	string	Billing address full name
address1	string	Billing address line 1
address2	string	Billing address line 2
city	string	Billing address city
postcode	string	Billing address zip/postcode
state_province_code	string	Billing address state/province code
country_code	string	Billing address country code

Products level

Parameter	Type	Description
product_id	string	SWAP's internal product id
shopify_product_id	string	Shopify's Product ID
shopify_variant_id	string	Shopify's Variant ID
order_number	string	The return's order number
original_order_name	string	Return order’s original order name
date	date	Date the product was created
product_name	string	Name of the product
variant_name	string	Name of the variant
full_sku_description	string	Product + Variant name
sku	string	SKU
main_reason_id	string	Id of the main reason for the return
main_reason_text	string	Text of the main reason for the return
sub_reason_id	string	Id of the sub reason for the return
sub_reason_text	string	Text of the sub reason for the return
comments	string	Customer's comments
item_count	number	Number of items
cost	number	Total cost
return_type	string	Return type. Can be one of the following: - Refund - Shop Now Credit - Shop Later Credit - Additional Payment - Recycle - Warranty
currency	string	Currency used by the customer
vendor	string	Name of the vendor
collection	list of string	List of names of the collections this product is part of
product_alt_type	string	Used to designate a different use case/type for a product outside of a normal return RMA (Recycle, refurbishment, etc.)
recycle_material	string	Used with the recycle feature. Collects the material type for the product being returned for recycling
grams	number	Product's weight, in grams
intake_reason	string	Dropdown options for each item on the returns dashboard. Used to keep a record of the condition of the item returned. Current values: - Sellable - Damaged - Missing - Wrong Item
tags	string	Product tags

Response sample

{
"from_date": "2023-07-05T12:16:42.267Z",
"to_date": "2023-07-05T12:25:42.267Z",
"next_from_date": "2023-07-05T12:23:05.817Z",
"limit": 50,
"returned": 2,
"remaining": 0,
"orders": [
{
   "order_name": "10112",
   "order_id": "5517725335776",
   "rma": "4366",
   "date_created": "2023-07-05T12:15:36.617Z",
   "date_updated": "2023-07-05T12:23:01.682Z",
   "type_string": "Shop Now Credit",
   "type": [
         "Shop Now Credit"   
      ],
   "shipping_status": "Pre-Transit",
   "status": "Open",
   "total": 0.00,
   "return_id": "1688559330975x718642940107030500",
   "shop_now_revenue": 73.00,
   "shop_later_revenue": 0.00,
   "exchange_revenue": 0.00,
   "refund_revenue": 0.00,
   "store_id": "1635427666272x611125723156784100",
   "total_additional_payment": 0.00,
   "total_credit_exchange_value": 73.00,
   "total_refund_value_customer_currency": 0.00,
   "store_name": "Swap Test Store",
   "customer_currency": "GBP",
   "customer_name": "John Doe",
   "screen_type": "Desktop",
   "customer_locale": "en",
   "shipping_carrier": "Royal Mail QR",
   "shopify_order_date": "2023-06-30T10:16:02-05:00",
   "shipment_from_address_country": "GB",
   "shipment_from_address_city": "Hounslow",
   "shipment_from_address_parcel_weight": 30.00,
   "shipment_from_address_state": "ENG",
   "tags": "men, swap_customfee"
	 "billing_address": {
      "name": "Pablo MC",
      "address1": "123 Evergreen Dr",
      "address2": null,
      "city": "Windsor",
      "postcode": "SL4 1RZ",
      "state_province_code": "ENG",
      "country_code": "GB"
   },
   "processed_by": "",
   "order_alt_type": "",
   "total_recycle_credit": 0.0,
   "num_recycled_products": 0,
   "total_weight_recycled_products": 0,
   "quality_control_status": "",
   "delivered_date": null,
   "products": [
{
   "product_id": "1688559321421x974696254738006000",
   "shopify_product_id": "8056297586912",
   "shopify_variant_id": "44046980808928",
   "order_number": "#10112",
   "original_order_name": "16175",
   "date": "2023-07-05T12:15:24.174Z",
   "product_name": "Adele One Shoulder Sequin Dress",
   "variant_name": "10",
   "full_sku_description": "Adele One Shoulder Sequin Dress 10",
   "sku": "SKU-ADELE-10",
   "main_reason_id": "1666606763782x167049510240911360",
   "main_reason_text": "Test 2",
   "sub_reason_id": "",
   "sub_reason_text": "",
   "comments": "",
   "item_count": 1,
   "cost": 65.00,
   "return_type": "Shop Now Credit",
   "currency": "GBP",
   "vendor": "Swap Test",
   "collection": [
   
],
   "product_alt_type": "",
   "recycle_material": "",
   "grams": 30,
   "intake_reason": "",
   "tags": ""
}
   ],
   "elapsed_days_purchase_to_return": null,
   "elapsed_days_return_to_delivery": null
} ,
{
   "order_name": "10112-2",
   "order_id": "5517725335776",
   "rma": "4368",
   "date_created": "2023-07-05T12:23:01.442Z",
   "date_updated": "2023-07-05T12:23:05.817Z",
   "type_string": "Shop Now Credit",
   "type": [
         "Shop Now Credit"   
      ],
   "shipping_status": "Pre-Transit",
   "status": "Open",
   "total": 0.00,
   "return_id": "1688559778610x221624197503254530",
   "shop_now_revenue": 594.00,
   "shop_later_revenue": 0.00,
   "exchange_revenue": 0.00,
   "refund_revenue": 0.00,
   "store_id": "1635427666272x611125723156784100",
   "total_additional_payment": 0.00,
   "total_credit_exchange_value": 594.00,
   "total_refund_value_customer_currency": 0.00,
   "store_name": "Swap Test Store",
   "customer_currency": "GBP",
   "screen_type": "Desktop",
   "customer_locale": "en",
   "shipping_carrier": "Royal Mail QR",
   "shopify_order_date": "2023-06-30T10:16:02-05:00",
   "shipment_from_address_country": "GB",
   "shipment_from_address_city": "Hounslow",
   "shipment_from_address_parcel_weight": 30.00,
   "shipment_from_address_state": "ENG",
   "tags": "men, swap_customfee"
   "billing_address": {
      "name": "Pablo MC",
      "address1": "123 Evergreen Dr",
      "address2": null,
      "city": "Windsor",
      "postcode": "SL4 1RZ",
      "state_province_code": "ENG",
      "country_code": "GB"
   },
   "processed_by": "",
   "order_alt_type": "",
   "total_recycle_credit": 0.0,
   "num_recycled_products": 0,
   "total_weight_recycled_products": 0,
   "quality_control_status": "",
   "delivered_date": null,
   "products": [
{
   "product_id": "1688559769690x970371949071695900",
   "shopify_product_id": "8056297586912",
   "shopify_variant_id": "44046980808928",
   "order_number": "#10112",
   "original_order_name": "16175",
   "date": "2023-07-05T12:22:52.398Z",
   "product_name": "Tie-waist wrap skirt black",
   "variant_name": "S / Black",
   "full_sku_description": "Tie-waist wrap skirt black S / Black",
   "sku": "",
   "main_reason_id": "1687934101057x162191378795724800",
   "main_reason_text": "Test 4",
   "sub_reason_id": "",
   "sub_reason_text": "",
   "comments": "",
   "item_count": 1,
   "cost": 530.00,
   "return_type": "Shop Now Credit",
   "currency": "GBP",
   "vendor": "Swap Test",
   "collection": [
   
],
   "product_alt_type": "",
   "recycle_material": "",
   "grams": 30,
   "intake_reason": "",
   "tags": ""
}
   ],
   "elapsed_days_purchase_to_return": null,
   "elapsed_days_return_to_delivery": null
} 
],
"version": 1
}

Related to

Returns V1