Returns Portal v2 Snippet

Configure the display of a Returns Portal in your shop that provides a streamlined returns process for your customers.

This page focuses on the embedded Returns Portal (web component snippet). If you want to use the hosted Returns App (no embed), jump to Hosted Returns App (no embed).

This article describes the v2 snippet configuration for the Returns Portal.

Setting Up the Returns Portal Snippet

The following instructions explain the basics of setting up the Returns Portal snippet and how you can customize the data settings in two easy steps, followed by optional advanced configuration for your Returns Portal.

1

Add the snippet to your website

To insert the snippet onto a page on your website or online shop:

1. Create an empty landing page, for example: at /returns-portal.
2. Copy the following snippet and paste it somewhere in the <body /> (not the <head />) of your page where you want the Returns Portal to be displayed.

The best place for the snippet would be a responsive content container of your page where the main content is usually displayed.

This will automatically load our JS snippet and default CSS. The plugin will be rendered in the defined DOM node.

<pl-returns-portal
  code="your-portal-code"
  account-name="parcellab-account-name"
>
</pl-returns-portal>

<script
  type="module"
  src="https://returns-app.parcellab.com/static/plugin/js/loader.mjs"
>
</script>

The plugin features automatic environment detection, so you can use the same snippet in your staging and production environments.

2

Modify the data settings

The data settings of the Returns Portal widget will have to be updated based on the following attributes:

Data Attribute	Necessity	Description	Example
code	Required	Your unique Returns Portal code.	xt-de
account-name	Required	Your parcelLab user ID or technical account name.	16147742 weareparkers
entry-point	Optional	The starting page for the Returns Portal. Default value is returns, where users start at the order search page. For orderless returns, set the value to registration.	registration
environment	Optional	This allows you to override the automatic environment detection. Default value is live, and uses the production server.	development staging live
lang	Optional	The ISO-2 language code for the initial language to load. The widget will be displayed in the specified language. This attribute can also be set via URL query parameter (for example: ?lang=de)	de

Here is an example of the snippet with modified data settings:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Returns Portal</title>
  </head>
  <body>
    <header>
      <h1>Our Returns Portal</h1>
    </header>

    <main>
      <div class="container">
        <pl-returns-portal code="xt-de" account-name="parkersdemo">
        </pl-returns-portal>
      </div>
    </main>

    <footer>
      <p>&copy; 2025 Powered by parcelLab</p>
    </footer>

    <script
      type="module"
      src="https://returns-app.parcellab.com/static/plugin/js/loader.mjs"
    ></script>
  </body>
</html>

3

Advanced configuration

Styling

The web component creates a shadow DOM to isolate styles and takes 100% width of its container.

To control the portal size, you can style the container element.

.returns-container {
  max-width: 1200px;
  margin: 0 auto;
  padding: 20px;
}

The element automatically adjusts its height to fit the content.

Environment Detection

The plugin automatically detects the environment based on the host URL (that is: your website):

• localhost → Development
• .parcellab.dev or staging* → Staging
• All other domains → Live/Production

You can also force a specific server via URL query parameter, like in the following example:

https://yoursite.com/returns?server=https://returns-app.staging.parcellab.dev

Draft Mode

To preview your draft Returns Portal configuration, append the query parameter draft=true to the end of the URL for your Returns Portal.

You can combine with language and server overrides, like in the following example:

https://yoursite.com/returns?draft=true&lang=de&server=https://returns-app.staging.parcellab.dev

URL Hash Navigation

The Returns Portal plugin supports hash-based navigation. Users can bookmark or share specific pages, like in the following examples:

• https://yoursite.com/returns#/registration/
• https://yoursite.com/returns#/12345/address/
• https://yoursite.com/returns#/12345/articles/

Browser Support

The plugin uses Web Components (Custom Elements) and requires modern browser support:

• Chrome/Edge 54+
• Firefox 63+
• Safari 10.1+

When using the ES module loader (loader.mjs), ensure browsers support ES modules. For legacy browsers, add the no-module fallback.

Legacy/No-module Fallback

If you need to support browsers without ES module support, add a no-module fallback.

Modern browsers will load the module, and legacy browsers will load the fallback.

The following example shows the plugin script with an additional no-module fallback script.

<script
  type="module"
  src="https://returns-app.parcellab.com/static/plugin/js/loader.mjs"
></script>
<script
  nomodule
  src="https://returns-app.parcellab.com/static/plugin/js/loader.latest.js"
  async
  defer
></script>

Content Security Policy (CSP)

If your site uses CSP headers, you need to allow the parcelLab returns domain in your policy:

frame-src 'self' https://returns-app.parcellab.com https://returns-app.staging.parcellab.dev;

For development environments, please include the following:

frame-src 'self' https://returns-app.parcellab.com https://returns-app.staging.parcellab.dev http://localhost:8000;

Required directives

• frame-src: Must include the returns portal domain(s)
• script-src: Must include the domain serving the loader script

Example CSP header including the parcelLab Returns domain

Content-Security-Policy:
  default-src 'self';
  frame-src 'self' https://returns-app.parcellab.com https://returns-app.staging.parcellab.dev;
  script-src 'self' https://returns-app.parcellab.com;

Troubleshooting

This section describes known errors and ways to troubleshoot common issues.

Returns Portal not loading

To troubleshoot this error:

1. Check browser console for errors
2. Verify code and account-name attributes are correct
3. Ensure the script tag is placed after the web component

Height issues

The plugin automatically adjusts height. If you see scrollbars, you can try the following:

• Ensure the container does not have a fixed height
• Check for CSS conflicts with the iframe

Navigation issues

The plugin uses hash-based routing.

To troubleshoot:

• Ensure your page does not conflict with hash changes
• Check that JavaScript is enabled

Hosted Returns App (no embed)

Use this when you want to send customers to parcelLab’s hosted returns experience. You do not add the <pl-returns-portal> snippet to your site, instead parcelLab will host your returns portal. You can access the hosted page directly from your Returns configuration in app.parcellab.com.

1) Standard returns login via order search (default)

By default, customers login with their order reference and their email address or shipping postal code.

• Native route of this portal when hosted: /<account>/<portal-code>/
• Embedded equivalent <pl-returns-portal code="<portal-code>" account-name="<account>"></pl-returns-portal>

To log a customer automatically in from e.g. their account section to the returns portal to initiate a return for a hosted or embedded portal, add reference (order number) and identifier (email or postal code) as query search parameters to the URL. If only one value is provided, the portal pre-fills that login field and the customer must enter the missing value before submitting. If reCAPTCHA is enabled, these values prefill the login form but do not auto-submit, so the customer must complete security verification before submitting.

Example: ...?reference=ORD-123&identifier=[e-mail]

2) Orderless registration entry

For orderless returns, customers do not have to provide an order number. Instead, they register their items to be returned manually or by searching the product catalog. This option needs to be activated in the returns portal options and a manual review of registered returns is recommended.

• Native route of this portal when hosted: /<account>/<portal-code>/registration/
• Embedded equivalent: <pl-returns-portal code="<portal-code>" account-name="<account>" entry-point="registration"></pl-returns-portal>

3) Receive UI entry (warehouse)

Use this UI to process returns in the warehouse if you do not have a WMS flow. Receiving a return in UI accepts the quantity and settles the return by issuing refunds and releasing exchanges where appropriate.

If your warehouse, store, or WMS should process returns by API instead, use Process Return Mutations.

The Receive UI requires the user to be logged in to parcelLab.

• Native route of this portal when hosted: /<account>/<portal-code>/receive/
• Note on embedding: The Receive UI is not designed to be embedded.

Deep linking to the returns portal (auto-login)

To send a customer straight into the returns flow, add the login parameters to the URL.

For an embedded portal (the <pl-returns-portal> snippet, with account-name and code already set), add them to your page URL, either in the query string or in the hash. All of these work:

https://<your-domain>/<your-returns-page>?reference=ORD-123&identifier=[e-mail]
https://<your-domain>/<your-returns-page>#?reference=ORD-123&identifier=[e-mail]
https://<your-domain>/<your-returns-page>#/?reference=ORD-123&identifier=[e-mail]

For the hosted portal, add them to the portal URL:

https://returns-app.parcellab.com/<account>/<portal-code>/?reference=ORD-123&identifier=[e-mail]

The supported parameters are:

• reference — the order number.
• identifier — email address or shipping postal code, depending on your portal settings.
• identifier_alternate — fallback identifier for postal-code or postal-or-email portals.
• security_hash — auto-login token tied to outbound tracking (used together with reference).

When embedded, the portal removes these parameters from your page URL after reading them, so the customer's details do not remain in the address bar, browser history, or shared links.

Supported Languages

The Returns Portal is available with default translations in the following languages. Dates and timestamps are automatically formatted according to the configured country and language for your Returns Portal.

List of supported languages

• Albanian
• Bosnian
• Bulgarian
• Chinese (simplified)
• Croatian
• Czech
• Danish
• Dutch
• English (UK)
• English (US)
• Estonian
• Finnish
• French
• German
• German (formal)
• Greek
• Hungarian
• Italian
• Japanese
• Korean
• Latvian
• Lithuanian
• Norwegian
• Polish
• Portuguese
• Romanian (formal)
• Serbian (Latin)
• Slovak
• Slovenian
• Spanish
• Swedish
• Turkish

To modify any of the default translations used in your Returns Portal, please contact your parcelLab representative.