Gorilla Return Labels Documentation
Everything you need to install, configure, and get the most out of Gorilla Return Labels on your WooCommerce store. Work top to bottom for a first install, or jump to a section from the sidebar.
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
Installation
- Upload and activate the pluginGo to Plugins → Add New → Upload Plugin, choose the zip from your purchase, click Install Now, then Activate.
- Run the setup wizardOn activation you’re redirected to a guided wizard: activate your license, connect EasyPost, and add your first return address. About five minutes.
- Open any WooCommerce orderGo to WooCommerce → Orders and open an order — the Return Label metabox in the sidebar is where all label generation happens.
Connecting EasyPost
Gorilla Return Labels uses EasyPost to shop USPS rates and generate labels. EasyPost handles the actual USPS integration; you sign up directly with them and pay USPS rates through them — no Gorilla Public markup on postage.
Getting your API key
- Sign upCreate a free account at easypost.com/signup.
- Find your keysGo to Account → API Keys in the EasyPost dashboard.
- Copy the production keyIt starts with EZAK.
- Paste it into the pluginWooCommerce → Return Labels → General.
EasyPost fees
EasyPost charges a tiny fee (around $0.01) per label purchased, on top of USPS postage — a few dollars a month at typical return volumes, with no monthly subscription. Postage is charged at USPS commercial rates, usually 20–30% below retail.
The setup wizard
- WelcomeAn overview of what you’ll need: a license key, an EasyPost account, and your return address.
- LicenseOn a development domain (localhost, .local, .test), licensing is bypassed automatically and dev mode is confirmed. Otherwise, click Activate License Key — SureCart’s activation page opens; enter your key, activate, and return to the wizard.
- Connect EasyPostPaste your production API key (EZAK). It’s stored in your WordPress database and sent only to EasyPost.
- Add return addressWhere returns ship back to. Pre-filled from your WooCommerce store settings — review and adjust. USPS requires a phone number on every label, so fill that field in. More addresses (a dropshipper’s return center, for example) can be added later in settings.
- DoneA summary with any outstanding items flagged, then off to your orders list to generate the first label.
License management
Found at WooCommerce → Return Labels → License. Statuses you may see:
You’re on a dev domain — licensing is bypassed automatically and the plugin runs without a key on this site.
Your license is valid and verified with SureCart. Full functionality available.
The plugin couldn’t reach SureCart’s servers to verify. It keeps working for 14 days and usually resolves on its own; if it persists, see Troubleshooting.
SureCart returned an explicit rejection — revoked, expired, or nonexistent key. Label generation is disabled until a valid key is entered.
No license key entered yet. Generate a label to see the license prompt.
Activating: click Activate License Key on the License tab, paste the key from your purchase confirmation email, and activate. Single-site licenses cover one activation — moving to a new site? Deactivate the old one first to free the slot.
Refresh status: license status is cached for 12 hours. Click Refresh License Status to force an immediate check against SureCart.
General settings
Found at WooCommerce → Return Labels → General.
Your production key from EasyPost, starting with EZAK. Required for all label operations. Stored in your WordPress database and only sent to EasyPost.
The USPS service initially selected when generating a label. Ground Advantage is usually right — cheapest, and plenty fast for returns. Priority Mail is faster but costs more. Overridable per label.
The fallback when a product has no dimensions set. For best results, keep accurate length, width, height, and weight on your products — the plugin auto-detects parcel sizes from that data.
Return addresses
Return addresses are where customer packages ship back to. Most stores use one; drop-shipping stores can add multiple — one for their own inventory, one per dropshipper’s return center.
To add one, scroll to Return Addresses on the General settings page, click + Add Return Address, and fill in: a nickname you’ll see when picking addresses on an order (“HQ,” “Main Warehouse”), a contact name (usually “Returns”), company, street address, city/state/ZIP, and a phone — required by USPS on every label. Save Changes confirms how many addresses saved.
Generating a return label
- Open a WooCommerce orderThe Return Label metabox appears in the sidebar of every order.
- Pick a return addressMultiple addresses? Choose from the dropdown; the first is selected by default.
- Verify parcel dimensionsAuto-filled from product data. Adjust if the return packaging differs, or expand Verify product dimensions for per-item inline editing.
- Click Preview CostUSPS rates across services, dimensional-weight analysis, worst-case projections, a risk badge, and a recommendation.
- Click Generate Scan-Based LabelThe 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 in the plugin — everything you need to know before committing to a label.
USPS rates
All available services for your parcel, sorted cheapest first, each with estimated delivery days. Ground Advantage is almost always the pick for returns. Flat Rate options show fixed pricing regardless of weight — useful when dimensional weight would otherwise blow up the cost.
DIM weight warnings
USPS charges dimensional weight on packages exceeding 1,728 cubic inches (one cubic foot); billable weight becomes whichever is greater — actual or dimensional. The formula: (L × W × H) / 166, rounded up. When DIM applies, the preview highlights the cubic inches, the calculated DIM weight, and the billable weight used for pricing.
Worst-case scenarios
Three “what if” projections warn you about adjustment risk: the customer uses a box one size up (+4 in per dimension, +1 lb), the customer grabs a 14×14×14 box, or the package weighs 50% more than expected. Scenarios that blow past your baseline get red dollar amounts.
Risk badge
Safe to generate.
Consider a flat-rate box or a larger dimension buffer.
Strongly consider flat-rate, or restrict packaging in your customer email.
Recommendation
A suggested service with reasoning, plus a ready-to-paste customer instruction naming the box size they should use.
Dimension verification
Below the return-address picker sits a collapsible Verify product dimensions section listing every product on the order with its length, width, height, and weight.
Missing dimensions
Products lacking dimensions highlight yellow with a “missing” tag, and the section auto-expands so you notice.
Save to catalog
A checkbox — Save these dimensions to the product catalog — is enabled by default when dimensions are missing. With it checked, Preview Cost or Generate saves your entered values back to the catalog first, then proceeds. Only changed values are saved; correct products aren’t touched.
One-off override
Uncheck the box to use your entered dimensions for this label only, leaving the catalog unchanged — useful when the return box differs from normal product packaging.
Recalculate parcel
After editing dimensions, click Recalculate Parcel to update the parcel fields (largest dimension across items, summed weights).
Customer email
Generating a label automatically emails the customer with the label PDF attached, a download link (in case the attachment doesn’t arrive), packaging instructions with a maximum recommended box size, drop-off guidance (any USPS location, or schedule a free pickup), and the tracking number. Sent from your site’s default address via wp_mail(). Lost email? Click Email to Customer on the existing-label view to re-send.
How scan-based billing works
You pay only when USPS scans
Generating a label creates it on EasyPost and assigns a tracking number — but no money changes hands yet. The charge executes when the customer drops off the package and USPS performs the first scan; that’s when postage bills to your EasyPost account.
Unused labels cost nothing
If a customer requests a label and never ships, you owe nothing. Ever. That’s the whole advantage over services that charge at label creation.
Voiding unused labels
Void any unscanned label from the metabox’s Void / Refund button. Scanned labels can’t be voided — the package is already in transit.
Label expiration
USPS scan-based labels are generally valid for about a year. Past that, USPS may accept them, or may flag, return, or destroy the package without refund eligibility. In practice, labels get used within weeks or never — the year window is plenty.
Adjustments & overcharges
USPS automatically measures and weighs packages at processing facilities. If the actual package exceeds the label’s dimensions, an adjustment charge hits your EasyPost account days or weeks after scanning.
Common causes
- Dimensional weight — the package exceeds 1,728 cubic inches and DIM pricing kicks in
- Oversize surcharges — the package exceeds certain dimensions
- Non-machinable packages — odd shapes, string-tied, or anything that can’t run on USPS sort equipment
How to minimize them
- Tell customers what box to use — the plugin writes the instruction; put it in your return email.
- Build buffer into parcel dimensions — if an item ships in a 10×8×4, label it 12×10×6 so a slightly bigger box doesn’t trigger anything.
- Use Flat Rate for DIM-risky items — Priority Flat Rate is fixed-price up to 70 lbs; no DIM calculation applies.
- Keep product dimensions accurate — predictions are only as good as your data, and the inline verification tool fixes it as you go.
Voiding & refunding labels
Any unscanned label can be voided for a full refund; scanned labels (in transit) cannot. Open the order, find the label in the metabox, click Void / Refund, and confirm — EasyPost submits the refund to USPS. USPS typically processes refunds in 2–3 weeks, back to your EasyPost balance.
Debug panel
Every labeled order has a collapsible Debug info section showing: API key mode (production vs test), the EasyPost shipment ID (click to copy), a direct EasyPost dashboard link, the tracking code (click to copy), the USPS service used, created date, which return address was selected, and the exact parcel dimensions the label was created with.
Fetch live status
A live API call to EasyPost returning current shipment status: whether it exists, what mode created it, real-time tracking state, and the addresses on file. Use it to verify a label really exists on EasyPost’s side, or to check whether a package has been scanned yet.
Clear label data
Wipes the plugin’s record from the order meta so you can regenerate. Void first — this doesn’t void anything on EasyPost.
Troubleshooting
License issues
“License required” shows on the order metabox
The plugin requires an active license on non-dev domains. Go to WooCommerce → Return Labels → License, click Activate License Key, enter your key, and activate.
“Grace period” status won’t clear
The plugin couldn’t reach SureCart to verify. It keeps working for 14 days and usually self-resolves. Persisting beyond a day? Check whether your site can reach app.surecart.com — some hosts or security plugins block it.
EasyPost errors
“EasyPost rejected your API key”
Wrong or revoked key. Copy it again from EasyPost dashboard → Account → API Keys, and make sure it’s the production key (EZAK) — not the test key (EZTK) — for real labels.
“Your EasyPost account balance is too low”
EasyPost bills against a prepaid balance. Log in, go to Account → Billing, and add funds — $20–50 lasts a while at small volumes.
“USPS couldn’t verify one of the addresses”
Check both the customer’s billing address and your return address — each needs a complete street, city, state, and valid ZIP. Verify questionable addresses at tools.usps.com/zip-code-lookup.
“A phone number is required”
USPS requires phone numbers on labels. Confirm your return address has one in plugin settings, and that the customer’s billing phone is populated on the order.
“No rates returned”
EasyPost couldn’t price the shipment — usually zero parcel dimensions/weight or an address verification failure. Check the parcel fields and confirm both addresses are valid.
Label issues
Label shows addresses in the wrong position
Old plugin version — pre-0.2.3 printed return labels with addresses reversed. Update, void affected labels, and regenerate.
Label is a PNG instead of a PDF
Old plugin version. Update to 0.2.5 or later — the plugin now requests PDF format explicitly.
Customer didn’t receive the email
Three checks: (1) WordPress email delivery — many hosts block wp_mail(), so use FluentSMTP or WP Mail SMTP with a real sender service; (2) the customer’s spam folder; (3) the Email to Customer button re-sends manually.
Metabox doesn’t appear on the order
Confirm WooCommerce is active, update the plugin (early versions had HPOS issues), and clear any caching plugins.
Billing & cost issues
EasyPost shows a charge I didn’t expect
Check the shipment’s status. “In Transit” or “Delivered” means the label was used and charged at scan. An adjustment line item means USPS corrected for dimension or weight discrepancies — see the Adjustments section.
Preview said $X but I was charged $Y
Usually a DIM weight adjustment — USPS measured the actual package and it exceeded the label’s dimensions. See Cost Preview & DIM Weight for prevention strategies.
