Project-7525: [DO NOT MERGE] Feature branch for the new returns flow

CHANGELOG.md

@@ -5,6 +5,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Draft
+- Implement guest return portal page (ORDERS-7736) [#2696](https://github.com/bigcommerce/cornerstone/pull/2696)
+- Add mobile and tablet responsiveness for returns list page (ORDERS-7771)
+- Add return details page (ORDERS-7751)
+- Add new create-return page [#2669](https://github.com/bigcommerce/cornerstone/pull/2669) 
 - Validate picklist option `available_to_sell` on PDP so Add to Cart is disabled and a "maximum purchasable quantity for {picklist} is {qty}" error is shown when the requested quantity exceeds a selected picklist item's stock, even when the main product still has enough stock [#2684](https://github.com/bigcommerce/cornerstone/pull/2684)
 - Render backorder prompts for bundled picklist options on the account order details page, using `linked_bundled_item` data per option; move parent item backorder prompts above the options list; reduce backorder prompt font size and add spacing between prompts and adjacent option rows [#2687](https://github.com/bigcommerce/cornerstone/pull/2687)
 - Hide option values on the PDP that would complete a "disable and hide" rule for the current selection, and steer the shopper off a default selection that is itself a forbidden combination [#2678](https://github.com/bigcommerce/cornerstone/pull/2678)
@@ -18,11 +22,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fix duplicate `id="default_instrument"` on Update Payment Method page [#2661](https://github.com/bigcommerce/cornerstone/pull/2661)
 - Respect `available_to_sell` on PDP so the Sold Out alert is hidden and the Add to Cart button stays enabled for backorderable products, and is disabled when quantity exceeds `available_to_sell` [#2659](https://github.com/bigcommerce/cornerstone/pull/2659)
 - Updated accessibility features [2656](https://github.com/bigcommerce/cornerstone/pull/2656)
+- Adds new guest-return-portal page. [2645](https://github.com/bigcommerce/cornerstone/pull/2645)
 - Update 'Ship to' copy for multi address orders [#2655](https://github.com/bigcommerce/cornerstone/pull/2655)
 - Fixed typo in category page reset-filters live region handler [#2643](https://github.com/bigcommerce/cornerstone/pull/2643)
 - Swap content/data keys in onProductOptionsChanged event detail [#2640](https://github.com/bigcommerce/cornerstone/pull/2640)
+- Gate Order Details "Return" button on `settings.returns_v2_enabled` with `settings.returns_enabled` fallback (ORDERS-7705)
 - Fix shipment info showing for cancelled orders [#2654](https://github.com/bigcommerce/cornerstone/pull/2654)
 - Render backorder prompts on My Account "Your orders" page [#2650](https://github.com/bigcommerce/cornerstone/pull/2650)
+- Gate account orders list "Return Items" link on returns settings (ORDERS-7704) [#2653](https://github.com/bigcommerce/cornerstone/pull/2653)
+- Added new Return list view (ORDERS-7717) [#2664] (https://github.com/bigcommerce/cornerstone/pull/2664) 
 
 ## 6.19.1 (04-09-2026)
 - Update stencil-utils versionto 6.23.0 [#2638](https://github.com/bigcommerce/cornerstone/pull/2638)

assets/js/app.js

@@ -3,6 +3,9 @@ __webpack_public_path__ = window.__webpack_public_path__; // eslint-disable-line
 import Global from './theme/global';
 
 const getAccount = () => import('./theme/account');
+const getCreateReturn = () => import('./theme/create-return');
+const getReturnDetails = () => import('./theme/return-details');
+const getGuestReturnPortal = () => import('./theme/guest-return-portal');
 const getLogin = () => import('./theme/auth');
 const noop = null;
 
@@ -12,13 +15,17 @@ const pageClasses = {
     account_addressbook: getAccount,
     shippingaddressform: getAccount,
     account_new_return: getAccount,
+    create_return: getCreateReturn,
+    guest_return_portal: getGuestReturnPortal,
     'add-wishlist': () => import('./theme/wishlist'),
     account_recentitems: getAccount,
     account_downloaditem: getAccount,
     editaccount: getAccount,
     account_inbox: getAccount,
     account_saved_return: getAccount,
     account_returns: getAccount,
+    account_return_detail: getReturnDetails,
+    return_detail: getReturnDetails,
     account_paymentmethods: getAccount,
     account_addpaymentmethod: getAccount,
     account_editpaymentmethod: getAccount,

assets/js/theme/create-return.js

@@ -0,0 +1,173 @@
+import PageManager from './page-manager';
+
+export default class CreateReturn extends PageManager {
+    onReady() {
+        const form = document.querySelector('[data-new-return-form]');
+        if (!form) return;
+
+        this.bindOrderLineItemEvents();
+        this.bindSubmit(form);
+    }
+
+    bindOrderLineItemEvents() {
+        // All three selects per row (qty, resolution, reason) trigger a submit-state check.
+        document.querySelectorAll('.newReturn-orderLineItem select').forEach(sel => {
+            sel.addEventListener('change', () => this.updateSubmitState());
+        });
+    }
+
+    updateSubmitState() {
+        const selectedItems = this.getSelectedItems();
+        const isValid = selectedItems.length > 0 && selectedItems.every(itemRow => {
+            const itemId = itemRow.dataset?.itemId;
+            if (!itemId) return false;
+            const resolutionEl = document.getElementById(`resolution-${itemId}`);
+            const reasonEl = document.getElementById(`reason-${itemId}`);
+            return resolutionEl && resolutionEl.value && reasonEl && reasonEl.value;
+        });
+
+        const submitBtn = document.getElementById('return-new-submitBtn');
+        if (submitBtn) submitBtn.disabled = !isValid;
+    }
+
+    bindSubmit(form) {
+        form.addEventListener('submit', async event => {
+            event.preventDefault();
+
+            // Ignore clicks while a request is in flight
+            if (this.isSubmitting) return;
+            this.isSubmitting = true;
+
+            const submitBtn = document.getElementById('return-new-submitBtn');
+            const overlay = document.querySelector('[data-new-return-view] .loadingOverlay');
+            if (submitBtn) submitBtn.disabled = true;
+            if (overlay) overlay.style.display = 'block';
+            this.clearError();
+
+            try {
+                const response = await this.createReturn(this.buildReturnInput());
+                const errorMessages = this.getErrorMessages(response);
+
+                if (errorMessages.length) {
+                    this.showError(errorMessages.join(' '));
+                    return;
+                }
+
+                this.showConfirmation();
+            } catch (error) {
+                this.showError(this.context.genericError);
+            } finally {
+                this.isSubmitting = false;
+                if (submitBtn) submitBtn.disabled = false;
+                if (overlay) overlay.style.display = '';
+            }
+        });
+    }
+
+    getErrorMessages(response) {
+        const transportErrors = Array.isArray(response?.errors) ? response.errors : [];
+        const returnErrors = Array.isArray(response?.data?.order?.return?.createReturn?.errors)
+            ? response.data.order.return.createReturn.errors
+            : [];
+
+        return transportErrors
+            .concat(returnErrors)
+            .map(error => error.message)
+            .filter(Boolean);
+    }
+
+    showError(message) {
+        const errorBox = document.getElementById('return-new-error');
+        if (!errorBox) return;
+
+        const messageEl = errorBox.querySelector('[data-return-error-message]');
+        if (messageEl) messageEl.textContent = message || '';
+        errorBox.style.display = '';
+    }
+
+    clearError() {
+        const errorBox = document.getElementById('return-new-error');
+        if (errorBox) errorBox.style.display = 'none';
+    }
+
+    // Storefront GraphQL `createReturn` mutation
+    createReturn(input) {
+        return fetch('/graphql', {
+            method: 'POST',
+            credentials: 'include',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.context.storefrontApiToken}`,
+            },
+            body: JSON.stringify({
+                query: `mutation CreateReturn($input: CreateOrderReturnInput!) {
+                    order {
+                        return {
+                            createReturn(input: $input) {
+                                entityId
+                                errors {
+                                    __typename
+                                    ... on Error {
+                                        message
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }`,
+                variables: { input },
+            }),
+        }).then(response => response.json());
+    }
+
+    // Swaps the form view for the success confirmation view.
+    showConfirmation() {
+        const formView = document.querySelector('[data-new-return-view]');
+        const confirmation = document.querySelector('[data-new-return-confirmation]');
+
+        if (formView) formView.style.display = 'none';
+        if (confirmation) confirmation.style.display = '';
+    }
+
+    /**
+     * Builds the `CreateOrderReturnInput` payload from the selected line items.
+     *
+     * @returns {{ orderEntityId: number, items: Array }}
+     */
+    buildReturnInput() {
+        return {
+            orderEntityId: parseInt(this.context.order?.id, 10),
+            items: this.getSelectedItems().flatMap(itemRow => {
+                const itemId = itemRow.dataset?.itemId;
+                if (!itemId) return [];
+                return [{
+                    lineItemEntityId: parseInt(itemId, 10),
+                    quantity: parseInt(document.getElementById(`qty-${itemId}`)?.value, 10),
+                    reasonEntityId: document.getElementById(`reason-${itemId}`)?.value,
+                    requestedResolution: this.buildRequestedResolution(document.getElementById(`resolution-${itemId}`)?.value),
+                }];
+            }),
+        };
+    }
+
+    // Maps a selected resolution value to a `RequestedResolutionInput`
+    buildRequestedResolution(value) {
+        const systemResolutionTypes = ['EXCHANGE', 'REFUND', 'STORE_CREDIT'];
+
+        if (systemResolutionTypes.includes(value)) {
+            return { type: value };
+        }
+
+        return { type: 'CUSTOM', customResolutionEntityId: value };
+    }
+
+    // Returns only row containers with a non-zero quantity selected.
+    getSelectedItems() {
+        return Array.from(document.querySelectorAll('.newReturn-orderLineItem')).filter(itemRow => {
+            const itemId = itemRow.dataset?.itemId;
+            if (!itemId) return false;
+            const qtyInput = document.getElementById(`qty-${itemId}`);
+            return qtyInput && parseInt(qtyInput.value, 10) > 0;
+        });
+    }
+}

assets/js/theme/guest-return-portal.js

@@ -0,0 +1,103 @@
+import PageManager from './page-manager';
+import NotFoundError from './not-found-error';
+
+export default class GuestReturnPortal extends PageManager {
+    onReady() {
+        const form = document.querySelector('[data-guest-return-portal-form]');
+        if (!form) return;
+
+        this.bindSubmit(form);
+    }
+
+    bindSubmit(form) {
+        form.addEventListener('submit', async event => {
+            event.preventDefault();
+            // Ignore clicks while a request is in flight
+            if (this.isSubmitting) return;
+            this.isSubmitting = true;
+            const submitBtn = document.getElementById('return-guest-submit-btn');
+            const overlay = document.querySelector('.guest-return-portal .loadingOverlay');
+            if (submitBtn) submitBtn.disabled = true;
+            if (overlay) overlay.style.display = 'block';
+            const payload = this.buildRequestPayload();
+
+            try {
+                const response = await this.startReturnGuestSession(payload);
+                const responseData = await response.json();
+                if (!response.ok) {
+                    throw new Error('Network response was not ok');
+                }
+
+                if (responseData?.errors?.length > 0) {
+                    throw new Error('Failed to start return guest session');
+                }
+
+                if (responseData?.data?.order?.return?.startReturnGuestSession?.errors?.length > 0) {
+                    for (const error of responseData.data.order.return.startReturnGuestSession.errors) {
+                        if (error.__typename === 'NotFoundError') {
+                            throw new NotFoundError(error.message);
+                        }
+                    }
+                    throw new Error('Failed to start return guest session');
+                }
+
+                window.location.href = `/create-return/${payload.orderEntityId}`;
+            } catch (error) {
+                if (error instanceof NotFoundError) {
+                    this.showError(this.context.notFoundError);
+                } else {
+                    this.showError(this.context.genericError);
+                }
+
+                this.isSubmitting = false;
+                if (submitBtn) submitBtn.disabled = false;
+                if (overlay) overlay.style.display = '';
+            }
+        });
+    }
+
+    buildRequestPayload() {
+        return {
+            email: document.getElementById('guest-return-email-input')?.value,
+            orderEntityId: parseInt(document.getElementById('guest-return-order-input')?.value, 10),
+        };
+    }
+
+    startReturnGuestSession(input) {
+        return fetch('/graphql', {
+            method: 'POST',
+            credentials: 'include',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.context.storefrontApiToken}`,
+            },
+            body: JSON.stringify({
+                query: `mutation StartReturnGuestSession($input: StartReturnGuestSessionInput!) {
+                    order {
+                        return {
+                            startReturnGuestSession(input: $input) {
+                                errors {
+                                    __typename
+                                    ... on Error {
+                                        message
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }`,
+                variables: { input },
+            }),
+        });
+    }
+
+    showError(message) {
+        const alertBox = document.querySelector('.guest-return-portal-error-container .alertBox');
+        if (!alertBox) return;
+
+        const messageElement = alertBox.querySelector('#alertBox-message-text');
+
+        alertBox.style.display = 'block';
+        if (messageElement) messageElement.textContent = message || '';
+    }
+}

assets/js/theme/not-found-error.js

@@ -0,0 +1,6 @@
+export default class NotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NotFoundError';
+    }
+}