RMA API (latest version) (Returns V2)

API Description

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

This is version 2 of the API, which introduces improvements such as split shipments, additional filters, and extended payload fields.

API Logic

When called, the endpoint returns a paginated list of RMAs for a given store and date range. Optional parameters allow filtering by submission time, 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-gateway.swap-os.com/returns-api

For UAT testing, use https://sandbox-apigw.swap-os.com/returns-api instead.

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 swap_store_id is required.

Parameter	Type	Required	Description	Example
swap_store_id	string	Yes	Store ID	123abc
rma_number	string	No	Filter by specific RMA number	RMA-2024-001
shopify_order_name	string	No	Filter by Shopify order name (#1234 format)	#1001
from_return_submission_date	string	No	Start date/time in ISO 8601 format — Only available for dates after August 1st	2024-01-01T00:00:00Z
to_return_submission_date	string	No	End date/time in ISO 8601 format — Only available for dates after August 1st	2024-01-31T23:59:59Z
last_RMA_updated_date	string	No	Filter returns updated after this timestamp (ISO 8601)	2024-01-15T00:00:00Z
submitted_at_from	string	No	Filter returns actually submitted after this timestamp	2024-07-01T00:00:00Z
submitted_at_to	string	No	Filter returns actually submitted before this timestamp	2024-07-31T23:59:59Z
api_version	number	No	API version (default: 2)	2
items_per_page	number	No	Number of results per page (1–100, default: 50)	25
page	number	No	Page number (default: 1)	1

Example Request

Request Method & URL

GET <https://api-mfdugldntq-nw.a.run.app/v2/external/returns?swap_store_id=store_123abc&from_return_submission_date=2024-01-01T00:00:00Z&to_return_submission_date=2024-01-31T23:59:59Z&page=1&items_per_page=25&api_version=2>

Headers

x-api-key: your_api_token_here

Body

Not applicable for GET requests.

cURL

curl -G "<https://api-mfdugldntq-nw.a.run.app/v2/external/returns>" \\   
 -H "x-api-key: your_api_token_here" \\   
  --data-urlencode "swap_store_id=store_123abc" \\   
  --data-urlencode "from_return_submission_date=2024-01-01T00:00:00Z" \\   
  --data-urlencode "to_return_submission_date=2024-01-31T23:59:59Z" \\   
  --data-urlencode "page=1" \\   --data-urlencode "items_per_page=25" \\   
  --data-urlencode "api_version=2"

Response Payload Overview

The API returns:

returns — an array of return records.
version — API version.
query_params — parameters used in the request.
pagination — pagination metadata.

Response Schema

Orders Array – Order Details

Field	Type	Description
rma_number	string	RMA number
return_id	string	Unique return identifier
shopify_order_name	string	Shopify order reference
order_id	string	Shopify order identifier
date_created	string	Return creation timestamp
date_updated	string	Last update timestamp
submission_date	string	When the return was first submitted
intention_date	string	Intention creation timestamp
type_string	string	Comma-separated return types
type	array	Array of return types (e.g. ["Refund", "Exchange"])
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
store_id	string	Store identifier
store_name	string	Store name
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
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

Customer Information

Field	Type	Description
customer_name	string	Customer full name
customer_email	string	Customer email
customer_national_id	string	National ID (if available)
customer_locale	string	Customer locale
customer_currency	string	Currency code

Processing Information

Field	Type	Description
rma_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
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

Addresses

Billing Address

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

Shipping Address

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

Shipments Array (new in version 2)

Field	Type	Description
shipment_id	string	Unique identifier for the shipment
location_id	string	Shopify location ID
destination_location_id	string	Destination location (for split shipments)
display_name_returns_portal	string	Display name in portal
carrier_id	string	Carrier identifier
postage_fee	number	Postage fee
label_type	string	Type of label (e.g. label, qr, own)
shipping_service	string	Shipping service name
display_name	string	Display name of the carrier
using_split_shipment	boolean	Whether using split shipment
label_provider_type	string	Label provider type
tracking_number	string	Return tracking number
tracking_url	string	Tracking link
package	object	Package weight and dimensions
items	array	Items included in this shipment

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
barcode	string	Barcode
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
total_refunded_taxes	number	Total refunded taxes
total_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

Additional Links

Field	Type	Description
portal_quick_link	string	Deep link for the customer to access their return

Example Response

Single Shipment

{
  "returns": [
    {
      "rma_number": "RMA-2024-010",
      "return_id": "RET-2024-010",
      "shopify_order_name": "#1010",
      "order_id": "gid://shopify/Order/9876543210",
      "date_created": "2024-02-05T09:10:00Z",
      "date_updated": "2024-02-05T12:30:00Z",
      "submission_date": "2024-02-05T09:15:00Z",
      "intention_date": "2024-02-05T09:10:00Z",
      "type_string": "Refund",
      "type": [
        "Refund"
      ],
      "shipping_status": "delivered",
      "status": "completed",
      "total": 29.99,
      "handling_fee": 0,
      "store_id": "store-123",
      "store_name": "Fashion Store",
      "customer_name": "John Doe",
      "customer_email": "[email protected]",
      "customer_currency": "USD",
      "quality_control_status": "passed",
      "delivered_date": "2024-02-05T11:45:00Z",
      "date_closed": "2024-02-05T12:00:00Z",
      "billing_address": {
        "name": "John Doe",
        "address1": "123 Main St",
        "city": "New York",
        "postcode": "10001",
        "state_province_code": "NY",
        "country_code": "US"
      },
      "shipping_address": {
        "name": "John Doe",
        "address1": "123 Main St",
        "city": "New York",
        "postcode": "10001",
        "state_province_code": "NY",
        "country_code": "US"
      },
      "shipments": [
        {
          "shipment_id": "SHIP-1001",
          "carrier_id": "fedex_ground",
          "shipping_service": "FedEx Ground",
          "tracking_number": "1Z111AA0000000001",
          "tracking_url": "<https://www.fedex.com/fedextrack/?trknbr=1Z111AA0000000001>",
          "items": [
            {
              "product_id": "PROD-200",
              "product_name": "Classic T-Shirt",
              "variant_name": "Medium / Blue",
              "sku": "TS-M-BLUE-001",
              "barcode": "1234567890123",
              "return_type": "REFUND",
              "cost": 29.99
            }
          ]
        }
      ],
      "portal_quick_link": "<https://returns.example.com/[email protected]&o=#1010&a=true>"
    }
  ],
  "version": 2,
  "query_params": {
    "swap_store_id": "store_123abc",
    "from_return_submission_date": "2024-02-01T00:00:00Z",
    "to_return_submission_date": "2024-02-29T23:59:59Z",
    "page": 1,
    "items_per_page": 25
  },
  "pagination": {
    "page": 1,
    "items_per_page": 25,
    "total_pages": 1,
    "total_items": 1,
    "has_next_page": false,
    "has_previous_page": false
  }
}

Split Shipments

{
  "returns": [
    {
      "rma_number": "RMA-2024-001",
      "return_id": "RET-2024-001",
      "shopify_order_name": "#1001",
      "order_id": "gid://shopify/Order/1234567890",
      "date_created": "2024-01-15T10:30:00Z",
      "date_updated": "2024-01-16T15:45:00Z",
      "submission_date": "2024-01-15T12:00:00Z",
      "intention_date": "2024-01-15T10:30:00Z",
      "type_string": "Refund, Exchange",
      "type": [
        "Refund",
        "Exchange"
      ],
      "shipping_status": "in_transit",
      "status": "processing",
      "total": 89.97,
      "handling_fee": 5,
      "store_id": "store-123",
      "store_name": "Fashion Store",
      "customer_name": "Jane Smith",
      "customer_email": "[email protected]",
      "customer_currency": "USD",
      "quality_control_status": "passed",
      "delivered_date": null,
      "date_closed": null,
      "billing_address": {
        "name": "Jane Smith",
        "address1": "456 Oak Ave",
        "city": "Los Angeles",
        "postcode": "90210",
        "state_province_code": "CA",
        "country_code": "US"
      },
      "shipping_address": {
        "name": "Jane Smith",
        "address1": "456 Oak Ave",
        "city": "Los Angeles",
        "postcode": "90210",
        "state_province_code": "CA",
        "country_code": "US"
      },
      "shipments": [
        {
          "shipment_id": "SHIP-001",
          "carrier_id": "fedex_ground",
          "shipping_service": "FedEx Ground",
          "tracking_number": "1Z999AA1234567890",
          "tracking_url": "<https://www.fedex.com/fedextrack/?trknbr=1Z999AA1234567890>",
          "items": [
            {
              "product_id": "PROD-123",
              "product_name": "Classic T-Shirt",
              "variant_name": "Medium / Blue",
              "sku": "TS-M-BLUE-001",
              "barcode": "1234567890123",
              "return_type": "EXCHANGE",
              "cost": 29.99
            }
          ]
        },
        {
          "shipment_id": "SHIP-002",
          "carrier_id": "ups_ground",
          "shipping_service": "UPS Ground",
          "tracking_number": "1Z999BB9876543210",
          "tracking_url": "<https://www.ups.com/track?tracknum=1Z999BB9876543210>",
          "items": [
            {
              "product_id": "PROD-124",
              "product_name": "Denim Jeans",
              "variant_name": "32 / Dark Blue",
              "sku": "DJ-32-DBLUE-001",
              "barcode": "9876543210987",
              "return_type": "REFUND",
              "cost": 59.98
            }
          ]
        }
      ],
      "portal_quick_link": "<https://returns.example.com/[email protected]&o=#1001&a=true>"
    }
  ],
  "version": 2,
  "query_params": {
    "swap_store_id": "store_123abc",
    "from_return_submission_date": "2024-01-01T00:00:00Z",
    "to_return_submission_date": "2024-01-31T23:59:59Z",
    "page": 1,
    "items_per_page": 25
  },
  "pagination": {
    "page": 1,
    "items_per_page": 25,
    "total_pages": 1,
    "total_items": 1,
    "has_next_page": false,
    "has_previous_page": false
  }
}

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:

/v2/external/returns?swap_store_id=store_123abc&from_return_submission_date=2024-01-01T00:00:00Z&page=2&items_per_page=25