Portal Customization

Updated 11 November 2026

Overview

This article explains the Theme styles and Branding cards on the Portal Customization page, and the matching panels in the Visual Editor, which shows the real portal beside the controls. Together they set the colours, fonts, logos and sidebar of the shopper's portal.

Use the menu on the left to quickly navigate this article.

Before you start

• Your logo files hosted at public, permanent URLs. Images are loaded from the URLs you paste, not uploaded.

Theme and branding

Opening the controls

In the admin, go to Shopper > Portal Customization, the Theme styles card. Open Visual Editor opens the two-pane editor; its Style customizations are Global Styles, Branding and Sidebar. Both places write the same settings: save with Save Changes on the settings page or in the Visual Editor.

Screenshot

The Visual Editor with the Sidebar panel open on the left and the live portal preview on the right

Global styles

• Corner radius: the rounding on cards, inputs and buttons, in pixels. Default: not set, which gives 10px on cards and 8px on buttons and fields.
• Accent color: a colour picker with a box for the hex value.
• Header font, Body font: each offers Default, Helvetica, Arial, Georgia and System Default, with a sample sentence underneath. Default is the font of the shopper's own device, so it looks close to System Default. Default: Default.
• Heading text color, Body text color: colour pickers. Default: #1E2230.
• Favicon image URL: the browser tab icon. Recommended: 64 x 64 px.
• Button color, Button text color: with a live Button preview.
• "Most popular" tag color: the chip next to Store credit in the credit option picker. Whether the chip appears is set under Policy > General, Store credit; the text flips to black or white to suit the colour you pick. A value without its # or that is not a colour falls back to the default and the page says so.
• Default design: reads Your portal is using the default design. while nothing is changed. Reset to Default Design returns the sidebar to Default, and colours, button colours, text colours, fonts and corner radius to the default design; logos, images and text stay saved. Shoppers see it once you save.

Note: If Notification branding has no accent colour of its own, resetting the design sends email buttons back to their default colour too.

Sidebar

The sidebar is the panel beside every portal page, and the band at the top on phones.

• Sidebar style: Default (the frosted light grey sidebar), Solid color (your colour, frosted; the sidebar text turns dark or white, whichever reads on it) or Background image (your photo fills the sidebar under a dark or light overlay). Default: Default.
• Sidebar color: shown with Solid color. Until you pick a colour the sidebar keeps the default look.
• Background image URL: shown with Background image. The photo that fills the sidebar on screens wider than 900 px. Recommended: 1620 x 2160 px, portrait (3:4). The sidebar takes 42% of the screen's width and its full height, for example 605 x 900 px on a 1440 x 900 screen and 806 x 1080 px on a 1920 x 1080 one, and less of the width on the review and status pages, so keep the subject near the middle or set Image alignment.
• Image alignment: which side of the photo stays in view when the sidebar crops it. Use it to keep a face or a product in the frame. Default: Center.
• Mobile background image URL: optional. The photo that fills the band at the top of the portal on screens up to 900 px wide, such as phones, in place of the desktop image. Recommended: 860 x 330 px, landscape. The band spans the screen's width (for example 390 or 430 px on a phone) and is about 140 to 160 px tall.
• Overlay: Dark (white text) or Light (dark text). A tint over the photo, strong enough that the sidebar text reads on any photo.

Screenshot

Shopper > Portal Customization, the Sidebar controls with Background image chosen and the overlay set to Dark

Branding

• Order lookup logo: the logo shown on a dark sidebar (a dark solid colour, or a background image with the dark overlay), so a light or white logo works best. With no light background logo, it also shows on a light sidebar. The preview shows which logo each page gets.
• Order lookup logo width: 200px, 300px, 400px or 500px. Default: 400px.
• Light background logo: the logo shown on a light sidebar (Default, a light solid colour, or the light overlay), so a dark logo that works on white works best. Recommended: 270 x 70 px. With no order lookup logo, it also shows on a dark sidebar.

Note: Shop Now's header and embed mode are light, so the order lookup logo shows on a light background there; the page warns Add a light background logo. when you have none. A colour that reads below 4.5:1 on the white cards gets a warning too, because text needs 4.5:1 to be easy to read.

Screenshot

The Branding card with both logos set and their previews

Return flow

In the admin, go to Shopper > Portal Customization and find Return flow. In the Visual Editor it sits under Style customizations, and the preview follows your choice.

• Return flow: how the shopper answers for each item on the order page. Multi-step asks about one item at a time in pop-ups. Single page shows every item on one page, with the reason, the questions and the exchange options beside each item. Default: Multi-step.

  Note: Single page changes the order page only. Order lookup, the review page and the status page stay the same, and your policies, reasons and exchange options carry over, so there is nothing else to set up. Reset to Default Design leaves this setting as it is. See Single page.

Screenshot

Portal Customization, the Return flow setting with Multi-step and Single page

What the shopper sees

The portal in these colours and fonts on every page, from order lookup to the status page, with the sidebar beside it on wide screens and as a band at the top on phones. Notification emails use their own logo and accent colour from Customize Branding on the Notifications page, falling back to the portal's.

Wording and content

This section covers the Content and Cancelled return message cards on the Portal Customization page, and the Text customizations panels of the Visual Editor. They hold the text shoppers read in the portal: the order lookup page, the footer on every page, the message on a cancelled return and, in the Visual Editor, the wording of every other page.

Before you start: Order lookup criteria set under Policy > General, because the lookup field's label follows them and cannot be typed here.

Order lookup content

In the admin, go to Shopper > Portal Customization, the Content card. The card reads To change the settings behind this content, go to your return policy settings. Everything saves with Save Changes in the bar at the foot of the page.

• Heading: the title on the order lookup page. Default: Returns and exchanges.
• Include subheading, Include graphic: under the heading, either a line of Subheading text or three Step graphics, each with an icon and a label. Click a tile to change the icon and edit the label below each one. Defaults: graphic, with Start a return, Select your unwanted items and Send it back.
• Input field placeholder: the placeholder in the order number box. Default: Order number. The lookup field label follows the Order lookup criteria in Policy > General and is read-only here, for example Shipping Zip Code or Email.
• Help tooltip: two lines shown behind the help icon. Default first line: You'll find your order number in your order confirmation email.
• Start button: the button label. Default: Start.

• Footer: two lines shown at the bottom of every page, with your support email. Use {{ link }} in the second line to place the contact link. Defaults: Questions? and Contact {{ link }}.

  Note: With no support email saved under Shopper > Notifications, the contact line is not shown.

Screenshot

Shopper > Portal Customization, the Content card with the heading, step graphics and footer fields

Cancelled return message

In the admin, go to Shopper > Portal Customization, the Cancelled return message card.

• Message: shown on the return status page after a return is cancelled. Default: No further action is needed. If you have questions, please contact support.
• Show a button: adds a button below the items on the cancelled return page, with its own Button text (default Continue Shopping) and Button URL. The button opens this URL in a new window. Default: off.

Page text in the Visual Editor

In the admin, go to Shopper > Portal Customization, click Open Visual Editor, then Text customizations. The panels are Global, Lookup Page, Order Page, Shop Now Page, Review Page and Return Status Page. Each panel lists every sentence on that page by group: headings, buttons, sections, reason and resolution wording, credit options, cart, and the unavailable-for-return messages. Type a replacement and the preview updates as you type. A blank field falls back to the default wording.

Screenshot

The Visual Editor's Review Page text panel with a heading changed and the preview updated

Note: Wording changes how something is described, not whether it is offered. Outcomes, windows and fees are decided by the policy.

What the shopper sees

Your wording everywhere it was changed. Item names, prices and dates are never editable here; they come from the order. When an order cannot be found, the lookup page's not-found sentence names the criteria ticked under Policy > General, for example We couldn't find that order. Check your order number and shipping zip code.

Portal address and embedding

This section covers the Custom portal domain and Embedded shopper return portal cards on the Portal Customization page. They decide where your shoppers' return portal lives: a free subdomain, your own domain, or embedded in a page of your Shopify storefront.

Before you start: A connected Shopify store. For your own domain, access to your DNS provider. For embedding, access to Online Store > Pages in your Shopify admin.

Settings

In the admin, go to Shopper > Portal Customization, the Custom portal domain card. Everything on the page saves together with Save Changes in the bar at the foot.

• Store name (required): your brand name. It sets your portal subdomain, shown under the box as Your portal subdomain: name.returnzen.app, which is used when Portal URL is blank. A name with no letters or numbers cannot generate a subdomain and the save is refused with Store name is required to generate your portal subdomain.
• Portal URL: your own domain for the portal, for example return.yourbrand.com. Enter a valid domain; https is added for you, and a path is refused. The helper Portal links will use shows the address portal links and emails will use.
• Show setup instructions: shows Add one CNAME record at your DNS provider: with the Host (your domain) and the Value (your returnzen.app subdomain), and the note Some providers want just the subdomain part in the Host field; root domains need ALIAS or CNAME flattening. On Cloudflare DNS, set the record to DNS only (grey cloud).
• Check DNS: looks the CNAME record up for the saved domain. It reads Verified: CNAME points at your subdomain, Verified: resolves to the same addresses as your subdomain (flattened setup)., or Not verified yet: no matching record found (missing, still propagating, or proxied). Flattened root domains verify by address once live. Save your changes before checking DNS; the check runs against the saved domain.

Screenshot

Shopper > Portal Customization, the Custom portal domain card with a Portal URL typed, the setup instructions open and Check DNS reading Verified

Connecting your own domain

1. Type the domain in Portal URL and click Save Changes.
2. Click Show setup instructions and add the CNAME record at your DNS provider.
3. Wait for DNS to update, then click Check DNS.
4. When it reads Verified, open the portal at your domain and run a test return.

Note: Not verified yet after adding the record usually means DNS has not propagated or the record is proxied; wait and check again. A root domain needs ALIAS or CNAME flattening and verifies by address once live.

Embedding the portal in your storefront

In the admin, go to Shopper > Portal Customization, the Embedded shopper return portal card.

• Embedded portal URL: a read-only address with a Copy button. Paste it into an iframe on a Shopify page to show the full return flow on your storefront.

1. Click Copy beside Embedded portal URL.
2. In your Shopify admin, open Online Store > Pages and edit a page.
3. Switch the editor to the code (<>) view.
4. Paste an iframe whose src is the embedded portal URL, for example with the style width:100%; height:900px; border:0.
5. Save the page.

The full return flow works inside the frame, and the portal renders without its own header there.

Screenshot

A Shopify page in code view with the iframe pasted, and the portal showing inside the storefront page

What the shopper sees

The portal at whichever address you chose. Notification emails link to it, so change the domain before you go live rather than after.

FAQ

Can I go back to Multi-step after trying Single page? Yes. Set Return flow back to Multi-step and save. Nothing else needs changing.

Can I upload a logo instead of pasting a URL? No. Host the image somewhere public and permanent, for example in Shopify's Files, and paste its URL.

Which logo do I need, or do I need both? One is enough if your sidebar stays one tone: a light logo for a dark sidebar, a dark logo for the Default or a light sidebar. Set both if you use a background image, because Shop Now and the embedded portal always use a light header.

The preview looks right but shoppers see the old design. Nothing changes for shoppers until you click Save Changes, on the settings page or in the Visual Editor.

Where do I change the placeholder for the zip or email box? You cannot. The label of that box follows the Order lookup criteria under Policy > General, in the order Zip code, Email, Phone number, so it always names exactly what the shopper can type.

Can I change the message shoppers from an uncovered country see? Not from the admin. The line below Start reads We can't accept returns from your country right now. Contact our support team for help. and has no field on this page.

Can I write the portal in another language? Yes, by replacing every sentence in the Visual Editor's text panels. There is one set of wording per store, not one per language.

Can I use my root domain, yourbrand.com, for the portal? Only if your DNS provider supports ALIAS or CNAME flattening, because a plain CNAME cannot sit on a root domain. A subdomain such as returns.yourbrand.com is simpler.

Do I need the custom domain to embed the portal? No. The embedded portal URL works with your free subdomain.

Shoppers see my old address in emails after I changed the domain. Emails already sent keep their links. New emails use the address under Portal links will use as soon as you save.

Please reach out to support@returnzen.app with any additional questions.