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 configuration for Returns Portal v2.

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.

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. 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)

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

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.

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.

Example: ...?reference=ORD-123&[email protected]

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.

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.

To send a customer straight into the returns flow, construct a URL like this:

Start with your hosted or embedded base URL.
Point it at the entry route (/ or /registration/).
Add /#/ before the query parameters
Append the query params (reference, identifier, ...).

If you embed the portal on your own site, your URL typically looks like:

https://<your-domain>/<your-returns-page>/#/<account>/<portal-code>/?reference=<ref>&identifier=<id>

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.

PreviousReturn Registrations NextConnect Order Data

Last updated 3 days ago

Was this helpful?

hashtagSetting Up the Returns Portal Snippet

hashtag Add the snippet to your website

hashtagModify the data settings

hashtagAdvanced configuration

hashtagTroubleshooting

hashtagHosted Returns App (no embed)

hashtag1) Standard returns login via order search (default)

hashtag2) Orderless registration entry

hashtag3) Receive UI entry (warehouse)

hashtagDeep linking to the returns portal (auto-login)

hashtagSupported Languages

Setting Up the Returns Portal Snippet

Add the snippet to your website

Modify the data settings

Advanced configuration

Troubleshooting

Hosted Returns App (no embed)

1) Standard returns login via order search (default)

2) Orderless registration entry

3) Receive UI entry (warehouse)

Deep linking to the returns portal (auto-login)

Supported Languages