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.