Connect ReturnGO: pull RMAs in by API, with return labels
Generate an API key in ReturnGO dashboard under Settings → API, copy the API server URL from the Servers section of the official API documentation, fill in the key, shop domain and server URL in Integration, pass a real read-only probe, then activate — RMAs are pulled in by API and return labels are supported.
The ReturnGO connector pulls returns (RMAs) from ReturnGO into the returns system (RMS) through the ReturnGO API: it reads the RMA list and RMA details, and return labels are supported by this connection. It works by API pull on a schedule — there is no webhook on this connection, so a new return in ReturnGO appears here at the next pull, not the instant it is created. The connection has four fields: an API key, your shop domain, the API server URL you copy from the official API documentation, and an optional header name.
Prerequisites#
- A ReturnGO account you can sign in to, with access to the dashboard Settings → API page.
- You know the shop domain registered in ReturnGO for the shop you are connecting — a domain such as demo-store.myshopify.com, not the shop display name shoppers see.
- You can open the official ReturnGO API documentation and find the Servers section — the API server URL for this connection is copied from there by you; there is no built-in default to fall back on.
- One ReturnGO API key can manage multiple shops, so keep track of which shop each connection is for — the shop domain field is what tells this connection which shop it is pulling.
Get your credentials#
- Sign in to the ReturnGO dashboard and open Settings → API.
- Generate an API key there and copy it in full. One key can manage multiple shops, so the same key can be used for more than one shop connection.
- Note the shop domain exactly as registered in ReturnGO, for example demo-store.myshopify.com. During requests this value is sent in the x-shop-name header, so copy the domain itself, not a display name.
- Open the official ReturnGO API documentation, find the Servers section, and copy the API server address shown there. This address is required and has to come from that section — do not guess one and do not reuse an address from a different document.
- Only if ReturnGO gave you a different API key header name during onboarding, note that name down too. In most cases the header name is x-api-key and there is nothing extra to collect.
Fill it into Integration#
- Open Integration → Connector Marketplace → ReturnGO → New connection.
- api_key — required, ReturnGO API Key: paste the key generated in ReturnGO dashboard → Settings → API, in full. It is a password-type field and is stored as a secret.
- shop_name — required, Shop domain: fill in the shop domain registered in ReturnGO, for example demo-store.myshopify.com. Fill the domain itself, not the shop display name — requests carry this value in the x-shop-name header.
- base_url — required, API server URL: paste the API server address you copied from the Servers section of the official ReturnGO API documentation, in the form https://… exactly as shown there. There is no default for this field: if it is left empty, the test stops before sending anything.
- api_key_header — optional, API key header name: leave it as x-api-key in the normal case. Fill it only when ReturnGO gave you a different header name during onboarding, and then fill that name exactly.
Test the connection#
Click Test connection. With credentials filled in, the test runs a real read-only probe: it sends GET {base_url}/rmas?pagesize=1 to the API server address you filled in, carrying your API key in its header (x-api-key by default, or the header name you filled in) and your shop domain in the x-shop-name header, and it allows 12 seconds for the answer. A successful answer — the probe succeeded message for GET /rmas — counts as a pass, because the probe proves the server address answers, the key is accepted, and the shop domain is recognised, while changing nothing. If base_url is missing, the test stops with MISSING_BASE_URL and sends no request at all; if the key or shop domain is missing, it fails openly on the missing credential instead of reporting a false pass. If you test with no credentials filled in at all, the result is a simulated check only and is labelled as simulated — fill in the three required fields and test again for the real probe.
Mapping / pick a template#
Pick the ReturnGO standard mapping. It works with what the API returns: the RMA list and the details of each RMA become return records here, and a pull can be narrowed by order number when you are looking for one return. After the test passes, run one pull and compare a real RMA side by side with ReturnGO — RMA reference, order reference, items and quantities — and check one return label flow for that return, before activating. If a field in ReturnGO differs from what you expect, adjust that field in the mapping instead of changing anything in ReturnGO.
Activate#
After activation, the connection pulls RMAs from ReturnGO into the returns system on the schedule you set — list and details together — and the warehouse works on those returns here, with return labels supported by this connection. Watch the first pulls in Runs / Logs and compare them with ReturnGO before leaving the connection unattended.
What this connection does not do: it does not receive returns by webhook, so a return created in ReturnGO is not pushed here the instant it happens — it arrives at the next scheduled pull. If a return is urgent, run a manual pull for it, narrowed by its order number, instead of waiting for the schedule.
FAQ#
Test stops with MISSING_BASE_URL
The base_url field is empty. This connection has no built-in server address: the probe needs the API server URL to know where to send GET /rmas, so with no address it stops before sending any request and reports MISSING_BASE_URL.
Open the official ReturnGO API documentation, copy the server address from the Servers section exactly as shown, paste it into base_url in the form https://…, save, and test again.
The probe fails even though the API key is correct
The probe checks more than the key: it also sends your shop domain in the x-shop-name header and talks to the address in base_url. The usual cause is shop_name: it holds a shop display name instead of the registered domain, so ReturnGO does not recognise the shop even though the key itself is valid. A base_url copied from the wrong place fails the same way.
Set shop_name to the domain registered in ReturnGO, in the form demo-store.myshopify.com, and re-copy base_url from the Servers section of the official API documentation. Keep the key as it is, save, and test again.
Should I fill in api_key_header?
In most cases, no. The header that carries your API key is x-api-key by default, and that default is already what the connection uses. The field exists only for shops that were given a different header name by ReturnGO during onboarding — filling in an invented name, or changing it without being told to, makes a working key look broken.
Leave api_key_header as x-api-key unless ReturnGO gave you a different name in writing during onboarding. If they did, fill that exact name; if you changed it while troubleshooting, set it back to x-api-key and test again.
The test passed with no credentials filled in — am I connected?
No. With no credentials at all, the test runs a simulated check only and labels the result as simulated. It never reaches ReturnGO, so it proves nothing about your key, your shop domain, or your server address.
Fill in all three required fields — api_key from Settings → API, shop_name as the registered domain, and base_url copied from the Servers section of the official API documentation — save, and test again. Only the GET /rmas probe result counts as a real pass.
Connected, but a new return in ReturnGO does not appear here
This connection pulls by API on a schedule and has no webhook, so a return created a minute ago correctly waits for the next pull. The other common cause is the shop: one API key can manage multiple shops, and this connection only pulls the shop named by its shop_name domain — a return created in a different shop under the same key will not appear here.
Confirm the return belongs to the shop whose domain is in shop_name, then run a manual pull — narrowed by the order number if you are looking for that one return — and check Runs / Logs. If it arrives on the manual pull, the connection is fine and the scheduled pull will bring the next ones.
The probe times out without an answer
The probe waits 12 seconds for the server at base_url to answer GET /rmas, and nothing came back in that time. That points at the address itself: a server URL copied from the wrong section, typed with a missing or extra part, or for a different environment than your shop uses will not answer this shop probe.
Re-copy base_url from the Servers section of the official ReturnGO API documentation, paste it exactly as shown without adding or removing anything, save, and test again. Do not change the key or shop domain while you are fixing the address — change one value at a time.