RMA API reference (Returns V2)

The RMA API lets your systems pull Swap return data. This article covers choosing a version, authentication, API keys, and filtering and pagination.

2 min readUpdated Oct 29, 2026

The RMA API lets your systems pull return data from Swap, for example into a warehouse management system (WMS) or an analytics tool. This article covers choosing a version, authentication, API keys, and filtering. For endpoints, request parameters and response schemas, see the RMA API documentation.

Choosing a version

The RMA API has two versions, each with its own endpoint. Use V2 for new integrations. V1 is maintained for integrations that already use it.

V1

V2

Shipments

One tracking number per return

A return_shipments array, one object per shipment, including split shipments

Exchange items

Not included

Included

Store credit

Not included

Included

Filters

Date range and last updated

Also RMA number, Shopify order name and customer email

Items per page

Up to 50

Up to 100

Portal quick link

Not included

Included

Authentication

Send your API key in the X-API-Key header with every request.

Identify the store with a query parameter. The parameter name depends on the version:

  • V1: store
  • V2: swap_store_id

One API key covers Swap's Returns APIs. If you already have a key for the Quality control API reference (Returns V2), use that rather than creating a second one. Keys for other Swap products, such as Global, don't work with the RMA API.

How to generate an API key

  1. Go to Returns → Integrations in the Swap dashboard.
  2. Click Generate API Key.
  3. Copy the key from the pop-up. It isn't shown again.

How to rotate your API key

  1. Go to Returns → Integrations in the Swap dashboard.
  2. In the API key panel, click the refresh icon.

Your current key is shown, masked, in the API secret key field, with the date it was last updated beneath it.

Rotating deactivates the old key immediately. Update your integration with the new key before you rotate, or requests will start failing.

Filtering and pagination

Each request returns a paginated list of RMAs for one store. Use the page and items_per_page parameters to move through the results.

You can filter by:

  • Both versions: the date the return was submitted, and the date the RMA was last updated.
  • V2 only: RMA number, Shopify order name and customer email.

To keep another system in sync, request RMAs updated since your last sync. To look up a single return, use V2 with the RMA number or the Shopify order name. The RMA API documentation lists the exact parameter names for each version.