Returns Portal v2

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

This article describes the configuration for Returns Portal v2.

Setting Up the Returns Portal

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

Add the snippet to your website

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

Create an empty landing page, for example: at /returns-portal.
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.

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.

If the value is set to registration, users will start at the login page.

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)

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>

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

Browser Support

The v2 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:

Check browser console for errors
Verify code and account-name attributes are correct
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

PreviousReturns Portal v1 NextConnect Order Data

Last updated 4 days ago

Was this helpful?