Connect Loop Returns: returns arrive by webhook, flag and process them in the warehouse

Create an API key with the returns scope in Loop admin under Returns Management → Tools & integrations → Developer Tools, fill that single key into Integration, understand why the test stays pending verification, then activate — returns arrive by webhook and the warehouse can flag and process them.

The Loop Returns connector connects your Loop returns portal to the returns system (RMS). Returns are not pulled in through the API: they arrive by webhook as shoppers create them in Loop. Once a return is in, the warehouse works on it here — flagging a return and processing a return are the two actions this connection provides. It does not create return labels. The connection has exactly one field, the Loop API Key.

Prerequisites#

• A Loop account you can sign in to as an admin, with access to Returns Management → Tools & integrations → Developer Tools.
• Returns are handled in Loop first: shoppers start returns in Loop, and this connection receives them — it is not a place to create a return from scratch.
• You understand the intake route before you start: returns arrive by webhook only, there is no scheduled API pull to wait for, and this connection does not provide return labels.

Get your credentials#

1. Sign in to Loop admin.
2. Go to Returns Management → Tools & integrations → Developer Tools.
3. Create a new API key there, and make sure the returns scope is included. The returns scope is a hard requirement: without it, the flag and process actions on returns will fail later.
4. Copy the key in full. When this system talks to Loop, the key is sent in the X-Authorization header — you do not fill that header anywhere yourself, you only fill the key.

Fill it into Integration#

1. Open Integration → Connector Marketplace → Loop Returns → New connection.
2. api_key — required, Loop API Key: paste the key you created in Loop admin → Returns Management → Tools & integrations → Developer Tools, in full, with the returns scope. It is a password-type field and is stored as a secret. There are no other fields on this connection: no shop address, no server address, nothing else to fill.
3. Save the connection, then run the test — and read the next section first, because the test result for this channel does not look like the others.

Test the connection#

Click Test connection and expect this result: with a real key filled in, the test does not come back as passed — it comes back as not passed, pending verification, and it sends no request to Loop at all. That is the expected behaviour for this channel, not a sign that your key is wrong. The reason is simple: Loop has no verified read-only check that can prove the key works without changing data. The known Loop actions, flag and process, change a return, so they cannot be used as a harmless test, and the read path for return details has not been confirmed from the official documentation. So the test checks only that a key is present, sends zero requests, and reports pending verification. Do not keep recreating keys to chase a green result — a correct key with the returns scope shows exactly this result. If you test with the key left empty, the result is a simulated check only and is labelled as simulated; it does not prove anything about a real Loop account.

Mapping / pick a template#

Pick the Loop Returns standard mapping. It takes a return that arrives by webhook and records it as a return in the returns system, with its return reference, order reference, items and quantities as sent by Loop. Before activating, walk one real return through: start a return in Loop, let it arrive, and compare the return here against Loop side by side — reference, items and quantities. If something does not line up, adjust that field in the mapping instead of changing anything in Loop.

Activate#

After activation, returns created in Loop arrive by webhook and appear as returns to work on. The warehouse opens a return here, flags it when it needs attention, and processes it when the return is handled — those two actions are sent to Loop for that return. Watch the first real returns in Runs / Logs and compare them with Loop before leaving the connection unattended.

What this connection does not do: it does not pull returns from Loop through the API on a schedule, so there is no sync button to wait for; and it does not create return labels, so shoppers keep getting their labels the way Loop itself provides them. Returns start in Loop, arrive by webhook, and are flagged and processed here.

FAQ#

I filled in a real key, but the test says not passed, pending verification

This is the expected result for Loop Returns, even with a perfect key. Loop has no verified read-only check that can prove a key works without changing data, so the test sends no request at all and reports pending verification. The result tells you a key is present — it does not tell you the key is wrong.

Stop recreating keys. Confirm the saved key is the one created in Loop admin → Returns Management → Tools & integrations → Developer Tools with the returns scope, then continue to mapping and activation, and judge the connection by the first real return arriving by webhook.

The test looked fine with no key, but nothing real ever happens

With the key left empty, the test only runs a simulated check and labels the result as simulated. That result never talks to your Loop account, so it cannot bring returns in or send flag and process actions out.

Create a real API key with the returns scope in Loop admin → Returns Management → Tools & integrations → Developer Tools, paste it into the api_key field, and save. After that, the test will show pending verification — for this channel, that is what a real key looks like.

Flagging or processing a return fails

The most likely cause is the API key itself: flag and process are the actions that talk to Loop, and they need a key created with the returns scope. A key created without that scope can sit in the connection looking complete, while every real action on a return is refused by Loop.

Create a fresh key in Loop admin → Returns Management → Tools & integrations → Developer Tools, this time including the returns scope, replace the saved api_key with it, and retry the flag or process action on the same return.

The connection is active, but no returns arrive

Returns only ever arrive one way on this connection: by webhook, at the moment a shopper creates a return in Loop. There is no API pull behind it, so an active connection with no new Loop returns will correctly show nothing new — and returns created before activation are not pulled in afterwards.

Start one real return in Loop and watch for it here and in Runs / Logs. If it arrives, the connection is working and the earlier quiet period simply had no new returns. If it never arrives, confirm the connection is activated with the correct key saved, then check Runs / Logs for that time window.

Shoppers ask where their return label is

This connection does not provide return labels at all. It receives returns and sends flag and process actions; the label a shopper prints comes from Loop itself, through whatever label arrangement you already have in Loop.

Keep the shopper label flow inside Loop and check your Loop label settings there. Use this connection for what it does: receiving the return here so the warehouse can flag and process it.

Which key should I use if I have several Loop API keys?

Only one key fits this connection: a key created under Returns Management → Tools & integrations → Developer Tools with the returns scope. Keys made for other purposes, or without that scope, will fill the field but the flag and process actions on returns will not work with them.

Pick the returns-scoped key, or create a new one following the credentials steps above, paste it into api_key in full, and save. There is only one field, so there is no second place a wrong key can hide.