Gorilla Returns Portal Documentation

Everything you need to install, configure, and get the most out of Gorilla Returns 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 8.0 or later
A free EasyPost account and production API key (for return labels)
A license key from gorillapublic.com

Scope. The plugin is US-only at launch and generates USPS return labels exclusively. Fully compatible with High-Performance Order Storage (HPOS); works with any WooCommerce admin theme; runs on any active WordPress theme without stylesheet conflicts.

Installation

Upload and activate the plugin. Go to Plugins → Add New → Upload Plugin, choose the zip from your purchase, click Install Now, then Activate.
Activate your license. Go to Returns → Manage License. Paste the license key from your purchase confirmation email and click Activate.
Connect EasyPost. Go to Returns → Carriers, paste your production EasyPost API key (starts with EZAK), and save.
Configure your policies. Go to Returns → Portal. Set your return window, reasons, and which resolutions to offer (exchange, store credit, refund). Every field has a sensible default so you can save immediately and refine later.
Point customers to /returns/. A public page has been auto-created for you at yourstore.com/returns. Add the link to your site navigation, or embed the portal on any other page with the [gorilla_returns_portal] shortcode.

Returns page not showing up? Go to Settings → Permalinks and click Save Changes. That forces WordPress to flush its rewrite rules. This is a one-time thing on some hosts.

Connecting EasyPost

Gorilla Returns 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 up. Create a free account at easypost.com/signup.
Find your keys. Go to Account → API Keys in the EasyPost dashboard.
Copy the production key. It starts with EZAK.
Paste it into the plugin. Returns → Carriers.

Want to test first? EasyPost also gives you a Test API Key (starts with EZTK) that generates free watermarked labels. Try the plugin with zero USPS charges, then switch to the production key for real returns.

Return addresses

Add at least one return address at Returns → Carriers → Return Addresses. This is where customer packages ship back to. Most stores use one; drop-shipping stores can add multiple. Each address needs a nickname, contact name, company, street address, city/state/ZIP, and a phone (USPS requires a phone number on every label).

The return portal page

Gorilla Returns creates a real WordPress page for the customer portal on activation. It lives at /returns/ by default and contains just the [gorilla_returns_portal] shortcode. This is the URL you point customers to.

Because it’s a real WordPress page (not a virtual URL), your theme handles the header, footer, and page chrome exactly like any other page on your site. You can also edit the page to add copy above or below the portal — return policy text, FAQ links, a hero banner, whatever.

Embedding on another page

If you already have a “Returns” or “Customer Service” page on your site, you can put the portal on that instead. Add the [gorilla_returns_portal] shortcode to your existing page’s content. The plugin auto-detects which page hosts the shortcode and routes form submissions correctly.

Rebuilding the auto-page

Deleted the auto-created page by accident? The plugin recreates it silently on the next request to /returns/. If it exists but is missing the shortcode, edit the page and re-add [gorilla_returns_portal] to the content.

Return policies

Set at Returns → Portal. Every field has a default that works out of the box — you only need to touch what you want to customize.

Return window

How many days after purchase a customer can file a return. Default 30. Anything older is rejected with the “This order is outside our N-day return window” message on the lookup screen.

Return reasons

The reason dropdown the customer picks per item. Edit as one reason per line, in the format slug | Label | requires_note — where a 1 in the third column forces the customer to add a note when selecting that reason (useful for “Defective” or “Wrong item shipped”).

Resolution options

Which resolutions to offer at the end of the flow:

Exchange: Customer picks a replacement variant (if the item has variants in stock) or writes what they want in an open-ended text field. Ships free — no return shipping fee applies. Replacement order is created in on-hold status and released to processing when the return arrives.
Store credit: Customer receives a WooCommerce coupon code for the return value, optionally with a bonus multiplier. Code is issued by you (the merchant) after the return arrives and passes inspection — never automatically at submission time.
Refund: Refund back to the original payment method, minus the return shipping fee you set on the RMA. You issue the refund through your normal WooCommerce refund workflow after the return arrives.

Return shipping fees

As of 4.6, return shipping fees are set per-RMA by you before approving, rather than being a single store-wide amount. Some returns cost more to ship than others; the per-RMA model lets you charge accurately.

Default suggested fee

Set at Returns → Portal → Default suggested shipping fee. This is the value that pre-fills the fee input on every new RMA so your staff doesn’t have to type a number from scratch on typical returns. It’s an admin-side default only — customers never see this number directly.

Set to 0 to force manual fee entry on every RMA.

Setting the fee per RMA

On any RMA detail screen (Returns → click into the RMA), the Return shipping panel has an editable input pre-filled with your default. Type the amount for this specific return, click Save, and the customer sees that number in their approval email as the shipping deduction.

Waiving the fee

Same panel: check Waive the return shipping fee and save. Use this when the return is due to a defect, wrong item shipped, or another merchant error — the customer keeps the full refund/credit amount with no deduction. Every waiver is recorded as an order note on the WooCommerce order for audit.

What the customer sees

The portal tells the customer a fee applies but does not quote a specific amount. The exact fee (or waiver) is confirmed in the approval email you send after you set the fee. This lets you charge accurately for each return without committing publicly to a fixed rate.

Exchanges are always free. The return shipping fee never applies to exchange resolutions, regardless of what you set on the RMA. Customers who choose exchange are continuing to spend with you — charging return shipping erodes goodwill for a resolution that already keeps money in-store.

Store credit

Store credit is offered as one of the three resolution options at the end of the customer flow. When issued, it takes the form of a native WooCommerce coupon code the customer enters at checkout.

Bonus multiplier

Set at Returns → Portal → Store credit bonus. Offer customers a higher amount in store credit than they’d get as a refund — a common lever is 110%, meaning $100 of return value becomes $110 in store credit. Set to 100 to disable the bonus.

The bonus is applied on the post-shipping-fee amount, not the gross return value. If a customer returns $50 of goods with a $9 shipping fee at a 110% bonus, they receive $45.10 in store credit (($50 − $9) × 1.10), not $55.

Merchant-authorized issuance

Store credit codes are NOT generated at customer submission — that would let someone grab a working discount code without ever returning anything. Instead:

Customer submits their return picking Store Credit. They see “Store credit is pending — we’ll email your code once your return arrives.”
You approve, generate a label, and the return ships.
When the physical return arrives and passes inspection, open the RMA detail screen. The Store credit issuance panel shows a breakdown table (return value − shipping × bonus).
Click Issue store credit code & email customer. The plugin generates the coupon in WooCommerce and emails the code to the customer in a single step.

Every issuance is recorded as an order note with your user name for audit (“Store credit $45.10 (code GR-A1B2C3D4) issued for RMA GR-xxxxx by [you]”). The panel prevents double-issuance — once issued, it shows the existing code and issued-at timestamp.

Exchanges

Exchanges are the friendliest resolution for both parties — the customer gets a working product, you keep the sale. Gorilla Returns handles them without the usual warehouse guessing.

Automatic variant picker

When a returned item is a variable product with variants in stock, the customer sees a visual picker on the Exchange step. They tap the variant they want (different size, different color) and submit. On your side, a replacement WooCommerce order is created automatically containing the picked variant.

Manual exchanges

When the item has no variants (or the customer wants to swap for something entirely different), the Exchange step shows an open-ended text field: “Tell us what you’d like to do.” The customer explains what they want, and you follow up manually with a quote or replacement offer.

Replacement order flow

For automatic exchanges, the replacement WooCommerce order sits in on-hold status by default. It doesn’t ship yet — you’re waiting for the customer’s return to arrive first.

When the return arrives and you mark the RMA complete, the replacement order automatically transitions to processing and enters your normal fulfillment queue. Customer gets a shipping notification when it ships out. No manual intervention required.

Need it faster? The portal copy tells customers who need their replacement sooner to place a new order right away — you can then refund the original once their return arrives. This turns “I need it now” into a second immediate sale instead of a stalled RMA.

Managing return requests

All active and past RMAs live at WordPress admin → Returns.

Pending-return notifications

Two visual cues so nothing gets missed:

Menu bubble. The Returns menu item shows a red count badge (e.g. “Returns (3)”) for RMAs in submitted status. Same visual language WordPress uses for Comments and Updates.
Top-of-page notice. A blue “X new return requests need your review” banner appears at the top of every wp-admin page when there’s pending work. Click “Review returns” to jump straight to the filtered list. Dismissible for 1 hour, auto-reappears on any new submission.

RMA list

The main Returns page. Columns: RMA token, order number, customer email, resolution requested, status, value, submitted date. Filter by status via the top-right dropdown or the tabs. Search by RMA token, order number, or customer email.

RMA detail

Click into any RMA to see everything: items being returned, reasons per item, customer notes, resolution requested, submitted date, and every action taken on the RMA. Panels appear or hide based on resolution type:

Return shipping — Fee input + waiver toggle. Only for refund/store-credit RMAs.
Store credit issuance — Preview and issue button. Only for store-credit RMAs.
Actions — Approve, reject, generate label, mark complete. Buttons change based on current status.

Approving an RMA

For refund and store-credit RMAs, set the return shipping fee first (or waive it). The Approve button shows a warning until you do — you can still approve without setting a fee, but the customer will be quoted the full amount with no deduction.

Clicking Approve generates the return label via EasyPost, saves the label URL and tracking number on the RMA, and emails the customer with the label attached as an inline PNG. All in one click.

Customer email templates

Every customer email has an editable Subject and Body in Portal settings. Blank fields fall back to the plugin’s default copy. Full list at Returns → Portal → Email templates:

Return submitted: Sent when the customer submits their request. Confirms receipt, states the resolution they picked, sets expectations for what happens next.
Return approved: Sent when you approve the RMA. Includes the shipping label (attached as a PNG) and, for refund/store-credit resolutions, the specific amount the customer will receive after the shipping deduction.
Return rejected: Sent when you reject the RMA.
Return completed: Sent when you mark the RMA complete. Copy varies by resolution — refund confirms the amount, exchange confirms the replacement is on the way, store credit confirms the code is now usable.
Store credit issued: Sent only when you click “Issue store credit” on the RMA admin. Contains the coupon code and the credit amount.

Placeholder tokens

Templates support placeholder tokens like {customer_name}, {rma_token}, {order_number}, {net_refund}, and {store_credit_code}. The full list with descriptions is expandable at the top of the Email templates section — click “Available placeholder tokens” to see all 13.

Unknown tokens are left in place as-is ({foo} renders as {foo}) so typos show up visibly in a test email rather than silently dropping.

Order number lookup

Customers who can’t find their order number can click “Can’t find your order number?” on the lookup form. They enter their email address, and the plugin emails them a list of their recent orders with order numbers, dates, and totals.

The feature is rate-limited (5 requests per hour per IP) and uses a same-success-message model — the customer sees “If we found any recent orders for that email, we’ve emailed a list to you” regardless of whether the email actually matched. This prevents someone from using the form to fish for whether an email is registered on your store.

Serial-returner blocklist

Set at Returns → Portal → Blocklist. Configure a threshold (e.g. “3 returns in the last 90 days”) and one of three actions:

Flag Least strict: Customer’s return goes through normally, but the RMA is tagged in your admin so you know to review it more carefully.
Review Manual intervention: Auto-approval is suspended for this customer; every return they submit sits in submitted status until you manually approve or reject.
Block Strictest: Customer is prevented from submitting new returns. They see a “Please contact us to arrange your return” message on the portal instead of the normal flow.

Analytics

Found at Returns → Analytics. Shows return rate, resolution split (exchange / store credit / refund), reason breakdown, and weekly trend over the past 12 weeks. Use it to spot patterns — which SKUs generate the most returns, whether a specific reason spikes after a product change, whether store credit adoption is trending up.

All data comes from RMAs in your own database — nothing is sent to any external analytics service. Merchants who need deeper reporting can query the wp_gorilla_rmas table directly.

License management

Found at Returns → Manage License. Statuses you may see:

Development Mode: You’re on a dev domain (localhost, .local, .test) — licensing is bypassed automatically and the plugin runs without a key.
Active: Your license is valid and verified with SureCart. Full functionality available.
Grace Period Works for 14 days: 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.
Invalid: SureCart returned an explicit rejection — revoked, expired, or nonexistent key. Label generation and portal are disabled until a valid key is entered.
Not Activated: No license key entered yet. The portal and label features stay hidden until you activate.

Activating: click Activate License Key on the License tab, paste the key from your purchase confirmation email, and activate. During the 3-day trial your card isn’t billed; the license auto-converts to annual billing at the end of the trial unless you cancel.

Refresh status: license status is cached for 12 hours. Click Refresh License Status to force an immediate check against SureCart.

Troubleshooting

Portal issues

“/returns/ shows a 404 or the wrong content”

Go to Settings → Permalinks and click Save Changes to flush rewrite rules. If the auto-created Returns page was deleted, the plugin recreates it on the next visit to /returns/.

“The portal renders but looks dark or unstyled”

The portal inherits your theme’s page styling. If it looks off, edit the auto-created Returns page and try a different page template from Page Attributes (e.g. “Full width” or “No sidebar” if your theme offers them).

“Continue button on the portal doesn’t advance the step”

Rare but possible if a security or caching plugin strips POST fields. Check your wp-content/debug.log (with WP_DEBUG_LOG enabled) for lines starting with [Gorilla Returns] Portal POST error — those tell you exactly what failed.

Label issues

“Approved, but label generation failed — check logs”

Something in the EasyPost request failed. Check wp-content/debug.log for lines starting with [GR Label_Bridge] — the error message from EasyPost is logged verbatim. Common causes: invalid customer phone number (the plugin auto-substitutes your return address phone in this case, but very old orders may not trigger the fallback), missing product dimensions on the returned item, or a temporarily unavailable EasyPost API.

“Customer says they didn’t receive the label email”

Three checks: (1) WordPress email delivery — many hosts throttle wp_mail(), so use FluentSMTP or WP Mail SMTP with a real sender service like Postmark, SendGrid, or Amazon SES; (2) the customer’s spam folder; (3) resend from the RMA detail screen by re-approving (which fires the email again).

“Label PNG is a placeholder instead of a real label”

The PNG fetch from EasyPost failed but the PDF label is available. Check debug.log for the specific error. The customer approval email falls back to a PDF link in this case, so they can still get their label.

Store credit issues

“Issue store credit button did nothing”

Check that the RMA’s resolution is store_credit (not refund or exchange) and that no code has been issued yet. The button hides after issuance to prevent double-issuance.

“Customer says the store credit code doesn’t work”

Codes are single-use and restricted to the email on the RMA. If the customer entered a different email at checkout, WooCommerce rejects the coupon. Also confirm the coupon is still marked active in WooCommerce → Coupons — deleting it there breaks the credit.

License issues

“License required” shows on the RMA admin

The plugin requires an active license on non-dev domains. Go to Returns → Manage 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.

Exchange issues

“Replacement order was created but never shipped”

Replacement orders sit in on-hold status by design — they don’t ship until the customer’s return arrives. Mark the RMA complete to release the replacement order to processing.

“Customer picked a variant that isn’t in stock anymore”

The plugin checks stock at portal-render time, but stock can change between the picker and submission. If the picked variant went out of stock, the replacement order sits in on-hold with a note; you’ll need to reach out to the customer and either restock, offer a substitute, or convert to a refund.

Still stuck? Email hello@gorillapublic.com with your plugin version (shown on the Plugins page), WordPress version, a clear description of what you’re trying to do and what’s happening, and screenshots — they help enormously. We reply within one business day.