Labels and Carriers

This page explains how return labels work, what the Lite edition does, and how to connect EasyPost in the Pro edition.

Label options at a glance

Option	Edition	What happens
Customer ships with their own label	Lite, Pro	The customer pays for and prints their own label. They get your instructions and return address. No file, no cost.
Upload a label PDF	Lite, Pro	You buy a label yourself and upload it on the return screen. The customer gets it by email.
Prepaid return label from EasyPost	Pro	ReturnDesk buys the label from the carrier service when you approve the return.
Drop-off point, Return in store, Keep the item	Pro	No label is needed.

Customer's own label

This is the default. When you approve the return, the customer gets the approval email with the Instructions for customer-supplied labels from the Rules settings and the Return address from the General settings. The return moves to Label sent. The customer presses I shipped it on the return page, with a tracking number if they have one.

Make sure the return address is complete. It is also the destination of every carrier label.

Uploading a label

On the return screen, an approved return shows Label bought elsewhere (PDF). Choose the PDF and press Upload label. The file must be a real PDF and at most 10 MB. ReturnDesk stores it privately, moves the return to Label sent and emails the customer a download link.

Customers download labels through a signed link that checks they own the return. They are never sent to the carrier's address.

Prepaid labels with a carrier (Pro)

Connect a carrier

1. Open WooCommerce > Settings > Returns > Labels.
2. Enter the credentials of the carrier service:

Carrier	Fields
EasyPost	EasyPost API key

3. Choose the carrier in Return label provider, and save.
4. In Rules > Return methods make sure Prepaid return label is allowed.

Credentials are stored encrypted. The REST settings endpoint never returns them, it only reports whether each one is set.

Complete Return address on the General tab first. Labels run from the customer's shipping address to that address. The parcel weight is the sum of the returned items' weights (1 kg when no product has a weight) and the size is the largest length, width and height of the items (30 x 20 x 10 cm when none is set). You can change the parcel with the tsre_label_parcel filter.

nota

Test the connection with your carrier's sandbox or test mode before you go live. You can point ReturnDesk at a sandbox address with the provider API base filters.

What happens when you approve

For a return with the Prepaid return label method, approving the return queues a background job. The job:

1. Asks the provider for rates.
2. Buys the cheapest rate, unless a rate was chosen on the return screen.
3. Stores the label and its PDF privately.
4. Adds the tracking to the original order. With WooCommerce Fulfillments switched on, the label becomes a shipment of the returned items tagged with the return id. Without it, the tracking goes into an order note.
5. Moves the return to Label sent, and sends the approval email with the label and tracking.

While the job runs, the customer's return page says "Your label is being prepared."

If the provider fails before anything was bought, the job is tried again up to three times. After the last failure the timeline shows a "Label failed" event and an admin notice appears.

Choosing a rate yourself

On an approved return, the Return label panel has a provider list and Get rates. The rates are kept for 15 minutes. Pick one and press Buy this label, after confirming the price. Void label cancels a label at the provider.

If a purchase may have gone through

If the carrier connection fails during the purchase itself (a timeout or a server error), ReturnDesk cannot tell whether you were charged. It does not retry on its own. An admin notice appears and the return screen says that a label purchase may have gone through. Check your carrier account, then use one of:

• Retry label, after ticking the box that says there is no label for this return.
• I checked the provider account and dealt with it: forget the unfinished purchase, to clear the warning and start again.

The warning stays until one of those, or until the same kind of provider settles it (a label it bought, or a plain failure at it). A failed manual upload or the customer's own label does not clear it, because neither says anything about the purchase. This is why a label is never bought twice.

Tracking webhooks (Pro)

Webhooks let the carrier tell ReturnDesk when the parcel is on its way and when it was delivered. The return then moves to On its way and Received by itself, and the timeline records a "Tracking update" once per carrier status.

The addresses are shown under each field on the Labels screen. They look like this (use your own domain):

Carrier	Address	How requests are verified
EasyPost	https://example.com/wp-json/tsre/v1/webhooks/easypost	The X-Hmac-Signature header, signed with your EasyPost webhook secret

Register the address in your carrier account for tracker or parcel status updates. For EasyPost enter the same secret on both sides.

How a request is handled:

1. A body over 1 MB is refused (413).
2. A request with a missing or wrong signature, or for a carrier that has no secret set, is refused with 403 before anything is read.
3. A body that is not JSON is refused (400).
4. Anything else answers 200 with { "handled": true|false, "changed": true|false }. Unknown parcels and statuses that ReturnDesk does not act on are acknowledged so the carrier stops retrying.

The log keeps the carrier, the status code and the last four characters of the tracking number, never the payload or the secret.

A return only moves along Label sent, On its way and Received, never backwards. A return that is still Approved, or already Cancelled or Rejected, is left alone. A delivered report on a return in Label sent goes through On its way first. You can change which carrier statuses count with the tsre_webhook_status_map filter.

Protecting label and photo files

Labels and customer photos are stored under wp-content/uploads/tsre/, in one folder per return, with random file names. Each folder has an index.php and an .htaccess that denies direct access (Apache and LiteSpeed). Files are handed out only through signed links.

On nginx the .htaccess file is ignored, so the files are protected only by their unguessable names. Block the folder in your server configuration:

location ^~ /wp-content/uploads/tsre/ {
    deny all;
}

Adjust the path if your uploads folder is elsewhere.