The SWAP Returns API enables you to retrieve return data from the Swap dashboard programmatically. This is useful for integrations with third-party systems like WMSs, marketing automation tools, analytics platforms, and more.
Authentication
To access the Returns API, an API token is required.
Generate API Token
⚠️ If you have previously generated an API key, for QC for example, you can use the same key.
To access the Returns API, you’ll need an API token.
Go to Returns → Integrations in the dashboard.
Click Generate API Key.
Copy the token from the popup — you won’t be able to see it again.
Include the token in the x-api-key header for all requests.
x-api-key: <API_TOKEN>
Note: Token generation is currently irreversible. There is no UI to revoke or regenerate keys. Contact support if needed.
Get RMA end point
<https://api-mfdugldntq-nw.a.run.app/v1/external/returns>
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 | Your store ID | "store_123abc" |
from_date | string | Yes | Start date for filtering returns (ISO 8601 format) | "2024-01-01T00:00:00.000Z" |
to_date | string | No | End date for filtering returns (ISO 8601 format) | "2024-01-31T23:59:59.999Z" |
items_per_page | number | No | Number of items per page (1–50, defaults to 50) | 25 |
page | number | No | Page number to fetch (defaults to 1) | 1 |
last_updated_date | string | No | Filter returns updated after this timestamp (ISO 8601) | "2024-01-01T00:00:00.000Z" |
version | number | No | API version number (defaults to 1) | 1 |
Parameter | Type | Description |
from_date | string | ISO 8601 format start datetime |
to_date | string | ISO 8601 format end datetime |
store | string | Store ID |
page | int | Page number for pagination |
items_per_page | int | Number of results per page |
Sample Request
GET /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 Host: api-gateway.swap-os.com Authorization: Bearer <API_TOKEN>
For UAT testing, use sandbox-apigw.swap-os.com as the host instead.
Sample Response
{ "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", ... }See full schema below.
Response Schema
The API returns a JSON object with the following top-level fields:
Field | Type | Description |
orders | array | Array of return records (see full structure below) |
version | number | API version number |
query_params | object | Parameters used in the request |
pagination | object | Pagination info (see Pagination) |
orders[]
Each return in the orders array includes the following fields:
Order Details
Field | Type | Description |
order_name | string | Order reference number |
order_id | string | Shopify order identifier |
rma | string | Return Merchandise Authorization 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’s full name |
customer_locale | string | Customer’s 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 (e.g. passed, failed) |
delivered_date | string | Date the return was delivered |
date_closed | string | Date the return was closed |
Time Metrics
Field | Type | Description |
elapsed_days_purchase_to_return | number | Days between original purchase and return |
elapsed_days_return_to_delivery | number | Days between return initiation and delivery |
elapsed_days_delivery_closed | number | Days between delivery and return 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 | ZIP/postal code |
billing_address.state_province_code | string | State/province code |
billing_address.country_code | string | Country code |
products[]
Each product object in the products array includes:
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 (e.g. REFUND) |
currency | string | Currency code |
Return Reasons (optional)
Field | Type | Description |
main_reason_id | string | ID for main reason |
main_reason_text | string | Description of main reason |
sub_reason_id | string | ID for sub-reason |
sub_reason_text | string | Description of sub-reason |
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 | Reason for product intake |
tags | string | Product tags |
is_faulty | boolean | Whether the item was 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 |
Error Responses
If a request fails, the API will return one of the following HTTP status codes:
Status Code | Meaning | When it occurs |
400 | Bad Request | Invalid or missing query parameters |
401 | Unauthorized | API key is missing or incorrect |
404 | Not Found | Store or return data not found |
500 | Internal Server Error | An unexpected error occurred on Swap’s servers |
Pagination
The Returns API supports pagination so you can retrieve results in smaller, manageable batches.
How it works
Use the page and items_per_page query parameters to control which results you get:
Parameter | Description |
page | Page number to retrieve (starts at 1) |
items_per_page | Number of returns per page (max: 50) |
Example:
/v1/external/returns?store=store_123abc&from_date=2024-01-01T00:00:00.000Z&page=2&items_per_page=25
This will return the second page of results, with 25 returns on each page.
Pagination fields in the response
The response includes a pagination object with the following fields:
Field | Description |
page | Current page number |
items_per_page | Number of items per page |
total_pages | Total number of pages |
total_items | Total number of items |
has_next_page | Whether more pages are available |
has_previous_page | Whether a previous page exists |
current_page_size | Number of items in the current page |
items_in_remaining_pages | Items remaining in later pages |
Best practices
Always include a from_date parameter to reduce the dataset size.
Start with page=1 and increment by 1 to loop through results.
Use has_next_page to keep paginating until all results are retrieved.
Use a lower items_per_page value (like 10 or 25) when testing.