The Integrations Page

Updated 11 November 2026

Overview

This article explains the Integrations page, where every outside service ReturnZen talks to has its own tile: Shopify for orders, EasyPost for labels, Stripe for card payments, Klaviyo for return events and marketing emails, and Zendesk for showing a shopper's returns beside their support ticket. Each tile shows whether the service is connected and opens that service's settings page. The article also covers webhooks on the Developer Tools page, which send return events to a URL you choose.

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

Shopper emails and shopper photos are hosted by ReturnZen and need no tile. Sending email from your own domain is set up under Shopper > Notifications; see Notifications: who sends the emails and who they come from.

The page

In the admin, go to Tools > Integrations. The pages under Tools are open to the Owner and Admins only.

Screenshot

Tools > Integrations, the grid of tiles with the status tabs above and the Categories rail on the left

• All, Available, Connected: tabs above the grid that filter the tiles. Available means not yet connected.
• Search integrations: a search box that narrows the grid by a tile's name, its line or its category.
• Categories: a rail that narrows the grid to All or one category: Commerce (Shopify), Shipping (EasyPost), Payments (Stripe), Email (Klaviyo) or Support (Zendesk). When nothing matches the filter, the grid reads No integrations match.
• Connect and Manage: the word on each tile. A tile that is not connected reads Connect; a connected one reads Manage, and so does a tile whose saved key cannot be read. A click anywhere on a tile opens that service's own page.

• The switch: every tile except Shopify has a switch in its top corner that enables or disables the integration without clearing its keys. Off means ReturnZen stops making live calls to that service until you switch it back on. On a tile that is not connected the switch cannot be turned on; its tooltip reads Connect [service] to enable it.

  Note: Shopify has no switch. Its tile shows a lock whose tooltip reads Required, always on: the Shopify connection is on for as long as it is connected.

• The detail line: a connected tile shows one detail under its name: the store domain on Shopify, the number of carriers on EasyPost, the business name on Stripe, and the account name on Klaviyo.

• Test mode: a chip on the EasyPost and Stripe tiles when the saved key is a test key. A live key shows no chip.
• Credentials cannot be read: a line on a tile whose saved key ReturnZen can no longer read. EasyPost, Stripe and Klaviyo keys are stored encrypted; if a saved key cannot be decrypted, open the tile and save the key again. Until then that service refuses its calls: no labels or tracking from EasyPost, no charges from Stripe, no events from Klaviyo. A tile that could not report its state reads Status could not be read; reload the page.

How it works

Switching an integration off and disconnecting it are different things. Off keeps the saved keys and is undone with one click on the switch. Disconnect clears the keys, and reconnecting means pasting them again. Each service's article says what stops in each case.

While EasyPost is switched off or has no key saved, returns get no shipping label. Shoppers are given the self-ship method and your return address, a manual return takes self-ship, and Create Shipping Label and Regenerate Label on the return page are disabled with a sentence saying why and a link to the EasyPost settings.

Important: While EasyPost is switched off, has no key, or has a key that cannot be read, carrier tracking is not read and returns waiting on a scan do not move. Instant Exchange charges whose ship-by date has passed are held, with a bell alert that reads Instant Exchange charges are on hold while EasyPost is switched off. Switch EasyPost on to resume them. They resume on the first night EasyPost is back.

If the page cannot load the grid it reads ReturnZen could not load your integrations just now. Reload the page to try again.

Webhooks for your own systems

In the admin, go to Tools > Developer Tools.

A service with no tile can still receive return events. On the Webhooks card, click Create Webhook, type the Webhook URL, choose the Events and click Save Webhook. ReturnZen then sends each chosen return event as JSON to that URL.

• Signing secret: each delivery is signed with its webhook's own secret, which starts whsec_. The delivery carries an X-Webhook-Signature header holding the HMAC-SHA256 of the raw request body. To verify a delivery, compute the same value with the secret and compare it to the header.

  Note: The secret is shown only once, when you create the webhook or click Regenerate Secret, in a window that reads Copy this signing secret now. It will not be shown again. Regenerating makes the old secret stop working immediately.

• Send Test: sends a signed test event to the webhook's URL and reports the HTTP status it got back.

• Active / Inactive: the chip on each webhook. Click it to deactivate the webhook or activate it again.
• Delete: the bin on a webhook's row opens Delete webhook?, which reads Events will no longer be sent to the URL and This cannot be undone.; click Delete Webhook. Regenerate Secret also asks first, with The current secret for the URL stops working immediately. Deliveries will fail verification until you update your receiver with the new secret.

Screenshot

Tools > Developer Tools, the Webhooks card with one webhook, its Active chip, Send Test and Regenerate Secret, and the Create Webhook button

API keys

The API keys card on the same page holds the keys your own systems use to read from ReturnZen.

• Generate API Key: opens a dialog with a Key name and Scopes; click Generate Key. The key is shown once, in a dialog that reads Copy this key now. It will not be shown again.
• The keys table: Scopes, Key, Name and Last used. The copy button beside a key copies the preview only, because the full key is shown once, at creation.
• Delete: the bin on a key's row opens Delete API key?, which reads Any integration using the key's name stops working immediately. This cannot be undone.; click Delete Key.

FAQ

Where do I set up email from my own domain? Not here. Go to Shopper > Notifications and open the Send from your own domain card. See Notifications: who sends the emails and who they come from.

Can I connect a second Shopify store? No. A different Shopify store is a different workspace. See Shopify.

Can I send return events to a service that has no tile? Yes. Create a webhook under Tools > Developer Tools. Each event is sent as JSON to the URL you choose and signed with that webhook's secret.

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