Gorilla Return Labels

Requirements

Before installing Gorilla Return Labels, make sure your site meets these requirements:

• WordPress 6.0 or later
• WooCommerce 7.0 or later
• PHP 7.4 or later
• A free EasyPost account and production API key
• A license key from gorillapublic.com

The plugin is US-only at launch and generates USPS return labels exclusively. It is fully compatible with High-Performance Order Storage (HPOS) and works with any WooCommerce admin theme.

Installation

1. Upload and activate the plugin
   In your WordPress admin, go to Plugins → Add New → Upload Plugin. Choose the zip file you downloaded from your purchase, click Install Now, then Activate.
2. Run the setup wizard
   On activation, you'll be redirected to a guided setup wizard. Follow the prompts to activate your license, connect EasyPost, and add your first return address. This takes about five minutes.
3. Open any WooCommerce order
   Once setup is complete, go to WooCommerce → Orders and open any order. You'll see a new Return Label metabox in the sidebar — that's where all label generation happens.

Connecting EasyPost

Gorilla Return Labels uses EasyPost to shop USPS rates and generate labels. EasyPost is a third-party shipping API — they handle the actual USPS integration so the plugin stays focused on what it does best. You sign up directly with EasyPost and pay USPS rates directly through them; there is no Gorilla Public markup on postage.

Getting Your API Key

1. Sign up for a free account at easypost.com/signup.
2. Go to Account → API Keys in your EasyPost dashboard.
3. Copy your Production API Key (starts with EZAK).
4. Paste it into the plugin's General settings at WooCommerce → Return Labels → General.

EasyPost Fees

EasyPost charges a tiny fee (around $0.01) per label purchased, on top of USPS postage. For typical return volumes this works out to a few dollars a month at most. There are no monthly subscription fees. Postage itself is charged at USPS commercial rates — the same rates the USPS website offers to business shippers, usually 20-30% below retail.

The Setup Wizard

The setup wizard walks new installs through five steps. Each step can be skipped and returned to later.

License Management

Found at WooCommerce → Return Labels → License. Manage your plugin license and check its status here.

License Status

The status displayed on the License tab tells you what state the license is in:

Development Mode You're on a dev domain — licensing is bypassed automatically. The plugin runs without a key on this site.

Active Your license is valid and verified with SureCart. Full functionality available.

Grace Period The plugin couldn't reach SureCart's servers to verify. Continues working for 14 days, usually resolves on its own. If it persists, see Troubleshooting.

Invalid SureCart returned an explicit rejection — the license has been revoked, expired, or never existed. Label generation is disabled until a valid key is entered.

Not Activated No license key has been entered yet. Generate labels to see the license prompt.

Activating a License Key

Click Activate License Key on the License tab. SureCart's activation page opens — paste your key from your purchase confirmation email and click Activate. The plugin validates the key and activates on this site. Each license has an activation limit (single-site licenses cover 1 activation). If you need to move the plugin to a different site, deactivate it on the old site first to free the slot.

Refresh Status

License status is cached for 12 hours to reduce API calls. Click Refresh License Status to force an immediate check against SureCart.

General Settings

Found at WooCommerce → Return Labels → General. These control core plugin behavior.

Return Addresses

Return addresses are the destinations where customer packages ship back to. Most stores use one (their warehouse or HQ). Stores that drop-ship can add multiple — one for their own inventory, one for each dropshipper's return center.

Adding an Address

On the General settings page, scroll to the Return Addresses section. Click + Add Return Address and fill in:

• Nickname — a short label you'll see when picking which address to use on an order (e.g., "HQ," "Main Warehouse," "Widgets Supplier Co.")
• Contact Name — usually "Returns" or a receiving department name
• Company — your business name or the dropshipper's name
• Street Address — line 1 and optional line 2
• City, State, ZIP — standard US format
• Phone — required by USPS on every label

Click Save Changes. A confirmation tells you how many addresses saved.

Address Order

The first address is pre-selected on the order metabox. If you have multiple addresses and most returns go to one specific location, put that one first to save clicks.

Generating a Return Label

1. Open a WooCommerce order
   Go to WooCommerce → Orders and click into any order. The Return Label metabox appears in the sidebar.
2. Pick a return address
   If you have multiple return addresses, use the dropdown to select which one applies for this return. The first address is selected by default.
3. Verify parcel dimensions
   The plugin auto-fills length, width, height, and weight from your product data. Adjust if the return packaging differs from the original shipment. You can also expand the Verify product dimensions section for inline editing per item.
4. Click Preview Cost
   See USPS rates across available services, dimensional weight analysis, worst-case cost projections, a risk badge, and a service recommendation.
5. Click Generate Scan-Based Label
   The label is created on EasyPost, saved to the order, and emailed to the customer automatically with packaging instructions.

Cost Preview & DIM Weight

The cost preview panel is the most important feature of this plugin. It shows you everything you need to know before committing to a label.

USPS Rates

All available USPS services for your parcel, sorted cheapest to most expensive. Each rate shows estimated delivery days. Ground Advantage is almost always the right pick for returns — cheap and reasonably fast. Priority Mail is 2-3 days but costs more. Flat Rate options show fixed pricing regardless of weight, which is useful when dimensional weight would otherwise blow up the cost.

DIM Weight Warnings

USPS charges based on dimensional weight for packages exceeding 1,728 cubic inches (one cubic foot). The billable weight becomes whichever is greater: actual weight or dimensional weight.

The DIM formula: (Length × Width × Height) / 166, rounded up.

When DIM weight applies, the preview panel highlights this clearly with the cubic inches, calculated DIM weight, and the billable weight used for pricing.

Worst-Case Scenarios

The plugin projects three "what if" scenarios to warn you about potential adjustment charges:

• Customer uses a box one size up — adds ~4 inches to each dimension and 1 lb
• Customer uses a 14×14×14 box — the common "grab whatever's around" scenario
• Package weighs 50% more than expected — extra packing material

If any scenario blows past your baseline cost significantly, red dollar amounts highlight the risk.

Risk Badge

Low Worst-case cost is within 25% of baseline. Safe to generate.

Medium Worst-case is 25-75% higher. Consider a flat-rate box or larger buffer.

High Worst-case is 75%+ higher. Strongly consider flat-rate or restricting packaging in your customer email.

Recommendation

A suggested service with reasoning and a ready-to-paste customer instruction explaining what box size they should use. Copy this into your return email to reduce adjustment risk.

Dimension Verification

Just below the return-address picker in the metabox, there's a Verify product dimensions collapsible section. It lists every product on the order with its length, width, height, and weight in inches and pounds.

Missing Dimensions

If any product lacks dimensions, the row highlights yellow and a "missing" tag appears. The section auto-expands when missing dimensions are detected so you notice them.

Save to Catalog

Below the dimension table, a checkbox labeled Save these dimensions to the product catalog is enabled by default when dimensions are missing. When checked, clicking Preview Cost or Generate Scan-Based Label saves the entered values back to the product catalog first, then proceeds normally.

Only values that have actually changed get saved. Products with correct dimensions aren't touched.

One-Off Override

Uncheck the save box to use your entered dimensions just for this label. The product catalog stays unchanged. Useful when the return box differs from the normal product packaging.

Recalculate Parcel

After editing dimensions, click Recalculate Parcel to update the parcel fields below based on the new values (largest dimension across items, summed weights).

Customer Email

When you generate a label, the plugin automatically emails the customer with:

• The label PDF as an attachment
• A download link to the label (in case the attachment doesn't arrive)
• Clear packaging instructions (maximum recommended box size)
• Drop-off guidance (any USPS location or schedule free pickup)
• The tracking number

The email is sent from your site's default "from" address using WordPress's wp_mail() function.

Re-Send Email

If the customer loses their email, click Email to Customer on the order's existing-label view. The email resends with the same attachment and tracking information.

How Scan-Based Billing Works

Scan-based return labels are the core value of this plugin. Here's exactly how the billing works.

You Pay Only When USPS Scans

When you click Generate Scan-Based Label, the label is created on EasyPost and assigned a tracking number — but no money changes hands yet. You've "reserved" the rate, but haven't paid.

The charge executes when the customer actually drops off the package and USPS performs the first scan. That's when postage is billed to your EasyPost account.

Unused Labels Cost Nothing

If a customer requests a label and never actually ships the package, you owe nothing. Ever. This is a huge win compared to traditional return services that charge you the moment the label is created.

Voiding Unused Labels

You can void any unscanned label from the order metabox's Void / Refund button. Labels that have already been scanned cannot be voided — at that point the package is already in transit.

Label Expiration

USPS scan-based labels are generally valid for about a year. After that, USPS may accept them but may also flag, return, or destroy the package without refund eligibility. In practice, most labels either get used within a few weeks or never — the year window is plenty.

Adjustments & Overcharges

USPS automatically measures and weighs packages at regional processing facilities. If the actual package exceeds the dimensions on the label, you'll receive an adjustment charge to your EasyPost account days or weeks after scanning.

Common Adjustment Causes

• Dimensional weight — package exceeds 1,728 cubic inches and DIM pricing kicks in
• Oversize surcharges — package exceeds certain dimensions
• Non-machinable packages — odd shapes, tied with string, or packaging that can't run on USPS sort equipment

How to Minimize Adjustments

1. Tell customers what box size to use. The plugin generates this instruction — use it in your return email.
2. Build buffer into parcel dimensions. If an item ships in a 10×8×4 box, label it for 12×10×6 so a slightly larger box doesn't trigger an adjustment.
3. Use Flat Rate boxes for DIM-risky items. USPS Priority Flat Rate has fixed pricing regardless of weight (up to 70 lbs). No DIM calculation applies.
4. Keep product dimensions accurate. The plugin's predictions are only as good as your product data. Every return is an opportunity to fix dimensions using the inline verification tool.

Voiding & Refunding Labels

Any unscanned label can be voided for a full refund. Labels that have already been scanned (the package is in transit) cannot be voided.

Voiding from the Metabox

Open the order, locate the existing label in the Return Label metabox, and click Void / Refund. Confirm the action when prompted. EasyPost submits the refund request to USPS.

Refund Processing Time

USPS processes refund requests in 2-3 weeks typically. The refund goes back to your EasyPost account balance, which you can then use for other labels or withdraw.

Clearing Label Data

After voiding, the metabox still shows the old label information. To wipe it and start fresh (for example, to generate a replacement label on the same order), expand the Debug info section and click Clear label data. This removes the plugin's record of the label from the order meta — it does NOT void the label in EasyPost, so make sure you've already voided it first if you no longer want to use it.

Debug Panel

Every order with an existing label has a collapsible Debug info section on the metabox. It exposes detailed technical information and power-user tools.

What's Shown

• API key mode — whether the label was generated with a production or test key
• Shipment ID — EasyPost's internal ID, click to copy
• EasyPost URL — direct link to view the shipment in EasyPost's dashboard
• Tracking code — click to copy
• Service — the USPS service used (Ground Advantage, Priority, etc.)
• Created date — when the label was generated
• Return address index — which of your return addresses was selected
• Parcel used — the dimensions and weight the label was created with

Actions

Troubleshooting