Connecting Your Shopify Store

Updated 11 November 2026

Overview

This article walks through connecting your Shopify store to ReturnZen. ReturnZen reads orders, products, customers and store credit from Shopify through a custom app that you create in your own Shopify admin. Connecting the store is the first screen after sign-up, and it is what creates your workspace. Afterwards the connection lives at Tools > Integrations > Shopify.

Use the menu on the left to quickly navigate this article.

Before you start

• A Shopify store where you can create custom apps (Settings, then Apps and sales channels, then Develop apps).
• The Owner login for ReturnZen. Only the store Owner can connect, test, replace or disconnect the Shopify connection.

Connecting the store

Create the custom app in Shopify

In your Shopify admin, go to Settings > Apps and sales channels > Develop apps.

1. Click Create an app and name it ReturnZen. The name matters: see Naming the Custom App.
2. Under the app's Admin API access scopes, tick every permission in the list below.
3. Install the app on your store.
4. Copy the app's Client ID and Client Secret. Shopify shows the Client Secret only once, so keep a copy somewhere safe.

ReturnZen needs these permissions:

• Orders: read_orders, write_orders, read_all_orders, write_order_edits
• Returns: read_returns, write_returns
• Products: read_products, write_products
• Customers: read_customers, write_customers
• Fulfillments: read_fulfillments
• Fulfillment orders: read_merchant_managed_fulfillment_orders, write_merchant_managed_fulfillment_orders, read_third_party_fulfillment_orders, write_third_party_fulfillment_orders, read_assigned_fulfillment_orders, write_assigned_fulfillment_orders
• Gift cards and store credit: read_gift_cards, write_gift_cards, read_store_credit_accounts, read_store_credit_account_transactions, write_store_credit_account_transactions
• Draft orders: write_draft_orders
• Inventory and locations: read_inventory, write_inventory, read_locations, read_markets
• Discounts: read_price_rules, read_discounts, write_discounts

Note: The six fulfillment order permissions are what let ReturnZen hold and refund EU and UK withdrawals of unshipped items. If the app is missing one of the fulfillment order permissions, the Shopify page under Tools > Integrations shows a warning naming it: Shopify connection problem. The ReturnZen app is missing these permissions in Shopify: and the names. Any other missing permission shows no warning, so check the list above when you create the app. Add it to the app in Shopify and save.

Screenshot

Shopify admin, Develop apps, the Admin API access scopes list with the ReturnZen permissions ticked

Connect the store

In ReturnZen, the first screen after sign-up is Connect your Shopify store.

1. Enter your Store domain: the myshopify.com address, without https://.
2. Paste the Client ID from the custom app.
3. Paste the Client secret from the custom app. ReturnZen stores it encrypted, and only your store's workspace can use it.
4. Click Connect Store. ReturnZen checks the pair with Shopify before saving. If Shopify rejects it, the form says so.

Screenshot

Onboarding step 1, Connect your Shopify store, with the Store domain, Client ID and Client secret fields and the Connect Store button

Name your store

The second screen is Name your store.

1. Check the Store name. It is fetched from Shopify and you can edit it. This one name becomes your workspace name and the store name shoppers see on the return portal.
2. Choose your Return portal address: the part before .returnzen.app. The address is checked for availability as you type.
3. If you like, answer How did you hear about ReturnZen? You can leave it empty.
4. Click Finish Setup.

ReturnZen then creates your workspace, secures your credentials and prepares your return policies, reasons and notification emails. A new store gets one policy, Default return policy. It is active, but every outcome and label creation are switched off, so nothing is offered to shoppers until you switch an outcome on under Policy > Return Policies.

Note: If this store was connected to ReturnZen before and then removed, the second screen reads Restore your store instead. Restoring re-links the store to your account with all of its previous data, settings and portal address, and the name and address are fixed on that screen. Click Restore Store. You can rename the store later under Shopper > Portal Customization.

Screenshot

Onboarding step 2, Name your store, with the Store name field, the Return portal address field showing ".returnzen.app is available" and the Finish Setup button

After connecting: the Shopify page

In the admin, go to Tools > Integrations > Shopify.

The page shows one of four statuses: No credentials saved, Your credentials not verified, Your credentials accepted or Your credentials cannot be read. Below it are the store, the Client ID, the authentication method and the API version Shopify is answering on. Three buttons sit at the bottom.

• Test Connection: asks Shopify right now and shows the store as connected if Shopify accepts the saved pair. It costs nothing and changes nothing else.
• Replace Credentials: saves a new Client ID and Client Secret for the same store. Nothing is saved until Shopify accepts the new pair; if Shopify rejects it or cannot be reached, your current connection stays as it is. A saved pair that can no longer be read is the one exception; see the FAQ below.
• Disconnect Shopify: clears the stored pair after a confirmation (Keep Credentials or Disconnect Shopify). Order lookup, label purchase and processing then stay paused until a store is connected again.

Important: The store domain is fixed while the store is connected, because every return in the workspace belongs to that store. To move to a different Shopify store, disconnect this one first.

Screenshot

Tools > Integrations > Shopify, the status pill reading Your credentials accepted, the connection details and the Test Connection, Replace Credentials and Disconnect Shopify buttons

Naming the custom app

This section covers why the custom app you create for ReturnZen is named ReturnZen, and what to do if you named it something else. Shopify records the app's name as the sales channel on every order the app creates, such as exchange orders and Shop Now orders. That name comes from the app itself, so ReturnZen cannot change it from inside the admin.

Before you start: A custom app created in your Shopify admin, as described in Connecting Your Shopify Store.

Name the app

In your Shopify admin, go to Settings > Apps and sales channels > Develop apps.

1. Open the app you created for ReturnZen.
2. Set the app name to ReturnZen.
3. Save.

A custom app named anything else shows that other name as the sales channel on every exchange and Shop Now order ReturnZen creates.

Screenshot

Shopify admin, Develop apps, the app's settings with the name field reading ReturnZen

What the shopper sees

Nothing. The app name is only what Shopify shows to you and your staff on orders. The name shoppers see on the return portal is the Store name you chose during onboarding, which you can change later under Shopper > Portal Customization.

FAQ

The status says Your credentials not verified. Are returns working? Yes. This happens when Shopify could not be reached at the moment you saved the pair, during an outage for example. The pair is saved and order lookup and processing run on it, but nothing re-checks it on a schedule. Click Test Connection: it asks Shopify now and shows the store as connected when Shopify accepts. While a saved pair is in force the connect form refuses a new one, so the other ways out are Replace Credentials and Disconnect Shopify.

The status says Your credentials cannot be read. What do I do? ReturnZen cannot read the stored Client ID and Secret. The Owner clicks Replace Credentials and pastes the pair again. If Shopify cannot be reached at that moment, the new pair is saved in place of the unreadable one and the store does not show as connected yet; click Test Connection once Shopify is reachable. Other users see the same banner with a request to ask the store Owner.

A banner says Shopify is answering on a different API version. Is anything broken? No. Your returns are still being processed. Send the banner text to support.

I already created the app under a different name. Do I start over? No. Rename it in Shopify. Then open Tools > Integrations > Shopify in ReturnZen and click Test Connection to confirm the connection still works.

Where does the sales channel name show up? On the orders ReturnZen creates in Shopify: exchange orders and Shop Now orders.

Please reach out to support@returnzen.app with any additional questions.