# Returns Portal v2 Snippet 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)](#hosted-returns-app-no-embed). {% hint style="info" %} This article describes the configuration for Returns Portal **v2.** {% endhint %} ## 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. {% stepper %} {% step %} #### 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 `` (*not* the ``) of your page where you want the Returns Portal to be displayed. {% hint style="info" %} The best place for the snippet would be a responsive content container of your page where the main content is usually displayed. {% endhint %} This will automatically load our JS snippet and default CSS. The plugin will be rendered in the defined DOM node. {% code overflow="wrap" %} ```html ``` {% endcode %} {% hint style="info" %} The plugin features automatic environment detection, so you can use the same snippet in your staging and production environments. {% endhint %} {% endstep %} {% step %} #### 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: ```html Returns Portal

Our Returns Portal

``` {% endstep %} {% step %} #### 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 v2 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#/registration/https://yoursite.com/returns#/12345/address/https://yoursite.com/returns#/12345/articles/) * [https://yoursite.com/returns#/12345/address/](https://yoursite.com/returns#/registration/https://yoursite.com/returns#/12345/address/https://yoursite.com/returns#/12345/articles/) * [https://yoursite.com/returns#/12345/articles/](https://yoursite.com/returns#/registration/https://yoursite.com/returns#/12345/address/https://yoursite.com/returns#/12345/articles/)

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](https://docs.parcellab.com/docs/developers/returns/configuration/v2#legacy-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: ```html 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** ```html 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; ```

{% endstep %} {% endstepper %} ## 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 `` 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: `///` * Embedded equivalent `` 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&identifier=user@example.com` #### 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: `///registration/` * Embedded equivalent: `` #### 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. {% hint style="info" %} The Receive UI requires the user to be logged in to parcelLab. {% endhint %} * Native route of this portal when hosted: `///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, construct a URL like this: 1. Start with your hosted or embedded base URL. 2. Point it at the entry route (`/` or `/registration/`). 3. Add `/#/` before the query parameters 4. Append the query params (`reference`, `identifier`, ...). If you embed the portal on your own site, your URL typically looks like: `https:////#///?reference=&identifier=` ## 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

{% hint style="info" %} To modify any of the default translations used in your Returns Portal, please contact your parcelLab representative. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.parcellab.com/docs/developers/returns/v2.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.