Connecting EasyPost

Updated 11 November 2026

Overview

This article walks through connecting EasyPost. Return labels are bought through EasyPost using your own EasyPost account and the carrier accounts attached to it. Until EasyPost is connected, no label is bought: a shopper on a policy that offers a label gets the self-ship method and your return address instead.

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

Before you start

• An EasyPost account with at least one carrier account enabled.
• A default return destination under Shipping > Destinations. The connection test ships to it, and a placeholder address fails the test.

The EasyPost page

In the admin, go to Shipping > Shipping Services, then click Manage Integration beside EasyPost.

The same page opens from the EasyPost tile under Tools > Integrations and from Connect EasyPost for shipping labels on the Home checklist.

EasyPost API key

1. Paste a key from your EasyPost account. A key starting EZTK is a test key and a key starting EZAK is a live key; ReturnZen reads the prefix and shows a Test mode or Live mode chip.
2. Click Save API Key.

Once saved, the field goes blank and shows Saved with the masked key. Leave it blank to keep the saved key, or type a new one to replace it. The Carrier Testing button in the page header opens your EasyPost account's API keys page.

Screenshot

The EasyPost API key card with a saved key, the Test mode chip and the Save API Key button

Test Connection

Click Test Connection to run a fake shipment against the saved key and pull a rate table. No label is bought. The result says in one line what happened:

• Rates came back: the connection is healthy, and the line names the service and price that would be chosen.
• No EasyPost API key is in use: paste a key above and save it.
• EasyPost is switched off, or no key is saved: the test does not run and the result names the cause. Switch EasyPost on under Tools > Integrations, or save a key.
• EasyPost returned an error: a 401 or 403 means the key is wrong; a 422 means EasyPost rejected your return destination address.
• Shipment created but 0 rates came back: in test mode, USPS only returns rates when both addresses are valid US addresses; in live mode, no carrier account is enabled for this key. Check Carriers in your EasyPost dashboard.
• Rates came back but none was selected: a carrier service filter is excluding everything. Check the policy's Labels & shipping settings.

Below the result, Raw response is the text to paste when asking support for help.

Screenshot

The Test Connection result box with a healthy result and the Raw response disclosure

Webhook signing secret

Carrier scans reach ReturnZen through a webhook you register in your EasyPost dashboard. Without it, ReturnZen never hears that a parcel was scanned: returns set to process in transit, out for delivery or on delivery do not process on their own, and a scan cannot revive an expired return. In the policy editor, the carrier processing event options carry the line Applies when EasyPost tracks the return: an EasyPost return label, or a tracking number the shopper entered.

1. Copy the Webhook address with Copy Address. It is https://api.returnzen.app/api/webhooks/easypost, the same for every store.
2. In EasyPost, open Webhooks & Events, click Add webhook, choose Production (or Test for a test key) and paste the address.
3. Paste the signing secret EasyPost gives you for that webhook into Webhook signing secret and click Save Webhook Secret.

Important: Tracking updates without a valid signature are refused, so the secret is required for tracking, not optional.

Screenshot

The Webhook signing secret card with the webhook address, the Copy Address button and the secret field

Carrier accounts

Available carriers lists every carrier attached to your EasyPost account. Carriers are added and removed in the EasyPost dashboard, not here. Edit Carrier opens the per-carrier page:

• Customized carrier service types: if toggled on, rate shopping uses only the service types you tick, so a route none of them serves gets no label. If toggled off, it uses every service type the carrier offers. Default: off.
• Label customization: choose the values printed in the carrier's custom label fields, with a prefix, a value, a suffix, custom text and a Show as a barcode switch. Some carriers do not print every field; generate a test label to check.

Disconnect EasyPost

Disconnect at the foot of the page clears the saved key after a confirmation. The dialog reads This clears your saved API key. Returns will get no shipping label until you save a new key. If an EasyPost key is also configured on the server, the dialog says instead that the server's key keeps buying labels until you switch the EasyPost integration off.

What the shopper sees

Once EasyPost is connected and a policy offers a prepaid label, the status page after submitting a return shows the label to print, or a QR code to show at a USPS counter where the policy allows printerless returns. The label ships from the shopper to your return destination, and the order number prints on it.

FAQ

Can I ship with a label bought on a test key? No. Labels bought with a test key are samples. In test mode USPS only accepts valid US addresses for both ends of the shipment.

Does ReturnZen add anything to the label price? No. EasyPost bills your EasyPost account for every live label, and ReturnZen does not add to that price.

What happens if I switch EasyPost off or the key cannot be read? With EasyPost switched off or no key saved, no label is bought: shoppers get the self-ship method and your return address, and Create Shipping Label and Regenerate Label on the return page are disabled, with a sentence saying why and a link to the EasyPost page. In both states, and with a key the server cannot read, tracking is not read and returns waiting on a carrier scan do not move. Instant Exchange charges due on a passed ship-by date are held, with a bell alert, and resume on the first night EasyPost is back. A key the server cannot read shows Credentials cannot be read on the tile; save the key again.

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