RMA API (Returns V2) | Swap Knowledge Base

API Description

The RMA API allows you to retrieve Return Merchandise Authorisation (RMA) data from Swap. This is designed for integrations with systems such as warehouse management systems (WMS), analytics tools, or other third-party applications that require return data.

API Logic

When called, the endpoint returns a paginated list of RMAs for a given store and date range. Optional parameters allow filtering by update time, controlling pagination, and specifying output version.

Authentication

All requests require an API token in the x-api-key header.

If you already have an API key for another Swap API (e.g. QC API), you can reuse it.

How to generate an API token

Go to Returns → Integrations in the Swap dashboard.
Click Generate API Key.
Copy the token from the popup (it will not be shown again).
Include it in the x-api-key header for all requests.

Note: Keys cannot be revoked or regenerated via the UI. Contact Swap Support if needed.

Header Example

x-api-key: your_api_token_here

Endpoint

Method: GET

URL:

<https://api-mfdugldntq-nw.a.run.app/v1/external/returns>

Headers

Key	Value	Required
x-api-key	Your API token	Yes

Query Parameters

You can include the following query parameters to filter and paginate results. Only store and from_date are required.

Parameter	Type	Required	Description	Example
store	string	Yes	Store ID	store_123abc
from_date	string	Yes	Start date/time in ISO 8601 format	2024-01-01T00:00:00Z
to_date	string	No	End date/time in ISO 8601 format	2024-01-31T23:59:59Z
items_per_page	integer	No	Number of results per page (1–50, default: 50)	25
page	integer	No	Page number (default: 1)	1
last_updated_date	string	No	Filter returns updated after this timestamp (ISO 8601 format)	2024-01-15T00:00:00Z
version	integer	No	API version (default: 1)	1

Example Request

GET <https://api-mfdugldntq-nw.a.run.app/v1/external/returns?store=store_123abc&from_date=2024-01-01T00:00:00Z&to_date=2024-01-31T23:59:59Z&page=1&items_per_page=25&version=1> x-api-key: your_api_token_here

For UAT testing, use sandbox-apigw.swap-os.com as the host instead.

Response Payload Overview

The API returns:

orders — An array of return records.
version — API version.
query_params — Parameters used in the request.
pagination — Pagination metadata.

Response Schema

Order Details

Field	Type	Description
order_name	string	Order reference number
order_id	string	Shopify order identifier
rma	string	RMA number
date_created	string	Return creation timestamp
date_updated	string	Last update timestamp
type_string	string	Comma-separated return types
type	array	Array of return types (e.g. ["Refund"])
shipping_status	string	Current shipping status
status	string	Current return status

Financial Information

Field	Type	Description
total	number	Total credit amount
handling_fee	number	Handling fee amount
return_id	string	Unique return identifier
shop_now_revenue	number	Revenue from shop now returns
shop_later_revenue	number	Revenue from shop later returns
exchange_revenue	number	Revenue from exchanges
refund_revenue	number	Revenue from refunds
store_id	string	Store identifier
total_additional_payment	number	Additional payment amount
total_credit_exchange_value	number	Total credit for exchanges
total_refund_value_customer_currency	number	Refund value in customer’s currency

Customer & Store Information

Field	Type	Description
store_name	string	Store name
customer_currency	string	Currency code
customer_name	string	Customer full name
customer_locale	string	Customer locale
shipping_carrier	string	Shipping carrier
shopify_order_date	string	Original order timestamp

Shipping Information

Field	Type	Description
shipment_from_address_country	string	Country of return origin
shipment_from_address_city	string	City of return origin
shipment_from_address_parcel_weight	number	Package weight in grams
shipment_from_address_state	string	State/province of return
tags	string	Tags applied to the return
tracking_number	string	Return tracking number

Processing Information

Field	Type	Description
processed	string	Whether the return is processed
processed_by	string	Name of person who processed it
order_alt_type	string	Alternative order type
quality_control_status	string	QC status
delivered_date	string	Date return was delivered
date_closed	string	Date return was closed

Time Metrics

Field	Type	Description
elapsed_days_purchase_to_return	number	Days from purchase to return
elapsed_days_return_to_delivery	number	Days from return initiation to delivery
elapsed_days_delivery_closed	number	Days from delivery to closure

Billing Address (optional)

Field	Type	Description
billing_address.name	string	Full name
billing_address.address1	string	Address line 1
billing_address.address2	string	Address line 2
billing_address.city	string	City
billing_address.postcode	string	Postal code
billing_address.state_province_code	string	State/province code
billing_address.country_code	string	Country code

Products Array

Field	Type	Description
product_id	string	Internal product ID
shopify_product_id	string	Shopify product ID
shopify_variant_id	string	Shopify variant ID
order_number	string	Order number
original_order_name	string	Original order name
date	string	Return date
product_name	string	Product name
variant_name	string	Variant name
full_sku_description	string	Full SKU description
sku	string	SKU code
item_count	number	Quantity returned
cost	number	Product cost
return_type	string	Return type
currency	string	Currency code

Return Reasons (optional)

Field	Type	Description
main_reason_id	string	Main reason ID
main_reason_text	string	Main reason description
sub_reason_id	string	Sub-reason ID
sub_reason_text	string	Sub-reason description
comments	string	Additional comments

Product Metadata (optional)

Field	Type	Description
vendor	string	Product vendor
collection	array	Product collections
product_alt_type	string	Alternative product category
grams	number	Weight in grams
intake_reason	string	Intake reason
tags	string	Product tags
is_faulty	boolean	Whether item is faulty

Tax & Duty Information

Field	Type	Description
refunded_taxes	number	Total refunded taxes
refunded_duties	number	Total refunded duties
refunded_inclusive_taxes	number	Refunded inclusive tax amount
refunded_inclusive_duties	number	Refunded inclusive duties amount
refunded_non_inclusive_taxes	number	Refunded non-inclusive tax amount
refunded_non_inclusive_duties	number	Refunded non-inclusive duties amount

Example Response

{
  "orders": [
    {
      "order_name": "SW-25066",
      "order_id": "11535622111613",
      "rma": "2313596",
      "date_created": "2025-01-06T15:15:58.250Z",
      "date_updated": "2025-01-06T15:17:00.863Z",
      "type_string": "Exchange",
      "type": [
        "Exchange"
      ],
      "shipping_status": "Own Label",
      "status": "Closed"
    }
  ],
  "version": 1,
  "query_params": {
    "store": "store_123abc",
    "from_date": "2024-01-01T00:00:00Z"
  },
  "pagination": {
    "page": 1,
    "items_per_page": 25,
    "total_pages": 5,
    "total_items": 120,
    "has_next_page": true
  }
}

HTTP Error Codes

Code	Meaning	When it occurs
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Invalid or missing API key
404	Not Found	Store or return data not found
500	Internal Error	Unexpected server error

Pagination

Use page and items_per_page to control results.

The pagination object in the response contains:

page
items_per_page
total_pages
total_items
has_next_page
has_previous_page
current_page_size
items_in_remaining_pages

Example:

/v1/external/returns?store=store_123abc&from_date=2024-01-01T00:00:00Z&page=2&items_per_page=25