Project-7525: [DO NOT MERGE] Feature branch for the new returns flow by bc-vivekaggarwal · Pull Request #2667 · bigcommerce/cornerstone

bc-vivekaggarwal · 2026-05-27T00:42:05Z

What?

This PR is for a feature branch to park all reviewed changes related to the new returns flow PROJECT-7525

Requirements

CHANGELOG.md entry added (required for code changes only)

Tickets / Documentation

PROJECT-7525

Screenshots (if appropriate)

Not applicable: They are part of individual PRs

Testing

TBD

Note

Medium Risk
Touches order return submission via Storefront GraphQL and broad account/order template gating, but changes are theme-scoped behind returns settings rather than core checkout or auth.

Overview
This PR lands the returns v2 storefront experience: shoppers can request returns on a new create-return page, see an updated returns list when v2 is on, and open a return details view. Entry points on the orders list and order details page are gated on settings.returns_v2_enabled with settings.returns_enabled as fallback.

The create-return page adds line-item quantity, preferred resolution, and reason controls, validates before submit, and posts the createReturn Storefront GraphQL mutation (with injected order context and API token) instead of the legacy form POST. Success swaps the form for an inline confirmation; errors surface in-page.

Account returns switches to returns-list-v2 (status badges, dates, item count, view-details link) when v2 is enabled; otherwise the legacy list remains. A new return details template renders RMA, status, line items, and a summary sidebar from return_detail context. A guest return portal page is added as a stub.

Supporting changes include new SCSS for create/detail layouts, status label styling, expanded lang/en.json copy, legacy add-return table a11y tweaks, and app.js page loaders for create_return and return detail page types.

^{Reviewed by Cursor Bugbot for commit 38101ea. Bugbot is set up for automated code reviews on this repo. Configure here.}

Copilot

Pull request overview

This PR parks initial Cornerstone theme changes for PROJECT-7525’s “new returns flow”, adding new templates/assets for a redesigned return-request experience and gating existing “Return” affordances on a new settings.returns_v2_enabled flag (with fallback to settings.returns_enabled).

Changes:

Add new return-related templates: a guest return portal page and a new account “add return” page layout.
Add new styling and a new page manager (AddReturnNew) plus bundle wiring for the new return-request UI.
Gate “Return” entry points in order details and orders list on returns settings; update CHANGELOG.md.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
templates/pages/guest-return-portal.html	New guest-facing return portal page scaffold.
templates/pages/account/orders/details.html	Gate “Return” button using `returns_v2_enabled` OR `returns_enabled`.
templates/pages/account/add-return-new.html	New account return-request page markup for the redesigned flow.
templates/components/account/orders-list.html	Gate “Return Items” link using `returns_v2_enabled` OR `returns_enabled`.
CHANGELOG.md	Add draft entries for the new return pages / gating changes.
assets/scss/components/stencil/addReturn/_addReturn.scss	Add styling for the new return-request page (`.newReturn`).
assets/js/theme/add-return-new.js	New page manager that renders the new return UI (currently with placeholder data).
assets/js/app.js	Wire `account_new_return` page type to load the new return page manager.

Comments suppressed due to low confidence (3)

assets/js/theme/add-return-new.js:96

Date formatting is hardcoded to the en-AU locale. This will display incorrect date formats for stores with different locales; use store locale from Stencil context (e.g. this.context.storeLocale) or omit the locale to allow the browser/store locale to drive formatting.

            // TODO ORDERS-7715: invoke createReturn Storefront GQL mutation.
        });
    }
}

assets/js/theme/add-return-new.js:142

Currency formatting is hardcoded to en-AU and always uses item.totalIncTax even though order.isTaxInclusive is available. This will display incorrect amounts/formatting for non-AU stores and for tax-exclusive display settings. Use a locale from context and choose totalIncTax vs totalExTax based on order.isTaxInclusive (or use server-provided formatted totals if available).
assets/js/theme/add-return-new.js:239
console.log('Submitting return', ...) should not ship in theme code. Either remove it or gate it behind an explicit debug flag, and replace with the real API call / proper error handling when wiring this up.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

    account_order: getAccount,
    account_addressbook: getAccount,
    shippingaddressform: getAccount,
-    account_new_return: getAccount,
+    account_new_return: getAddReturnNew,
    'add-wishlist': () => import('./theme/wishlist'),


+{{> components/common/breadcrumbs breadcrumbs=breadcrumbs}}
+
+<h1> Guest Return Portal</h1>
+


+        </div>
+        <div class="newReturn-headerActions">
+            <a href="{{../urls.account.orders.all}}" class="newReturn-btnBack">{{lang 'account.orders.return.back_button'}}</a>
+            <a href="/return-policy" class="newReturn-btnPolicy">View return policy &rarr;</a>
+        </div>
+    </div>
+    {{#if date}}<p class="newReturn-orderDate">{{date}}</p>{{/if}}


+        this.bindSubmit($form);
+    }
+
+    bindOrderLineItemEvents() {
+        document.querySelectorAll('.newReturn-stepperBtn').forEach(button => {
+            button.addEventListener('click', () => {
+                // Derive itemId from the parent row — buttons do not carry data-item-id,
+                // so the [data-item-id] selector stays scoped to the row container only.
+                const row = button.closest('.newReturn-orderLineItem');
+                const itemId = row?.dataset?.itemId;
+                if (!itemId) return;
+                const action = button.getAttribute('data-action');


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


denis-bc · 2026-05-28T01:47:53Z

cursor review

cursor · 2026-06-17T01:14:51Z

+        </div>
+        <div class="newReturn-headerActions">
+            <a href="{{../urls.account.orders.all}}" class="button">{{lang 'account.returns.back'}}</a>
+            <a href="/return-policy" class="button button--primary">{{lang 'account.returns.view_return_policy'}} &rarr;</a>


Return policy URL not localized

Medium Severity

The “View return policy” action points to a root-absolute /return-policy path instead of a storefront-aware URL, so it can 404 or miss the language subfolder on multi-language channels.

^{Reviewed by Cursor Bugbot for commit 621d2ce. Configure here.}

cursor · 2026-06-23T00:06:21Z

+                    requestedResolution: this.buildRequestedResolution(document.getElementById(`resolution-${itemId}`)?.value),
+                }];
+            }),
+        };


Additional note omitted from payload

Medium Severity

The create-return page collects an “Additional Note” in data-new-return-note, but buildReturnInput() never reads that field, so shopper notes are dropped and never sent with the createReturn mutation.

Additional Locations (1)

templates/pages/create-return.html#L102-L108

^{Reviewed by Cursor Bugbot for commit bcea92e. Configure here.}

cursor · 2026-06-23T00:06:21Z

+
+    // Storefront GraphQL `createReturn` mutation
+    createReturn(input) {
+        return fetch('/graphql', {


GraphQL URL ignores storefront base

Medium Severity

createReturn posts to a hardcoded /graphql path. On multi-language subfolder storefronts, that can miss the localized base URL used elsewhere for theme API calls, so the mutation may hit the wrong host path and fail.

^{Reviewed by Cursor Bugbot for commit bcea92e. Configure here.}

cursor · 2026-06-23T00:06:21Z

+                    <select class="form-select form-select--small" id="resolution-{{id}}" aria-label="{{lang 'account.returns.select_resolution'}}">
+                        <option value="">{{lang 'account.returns.select_resolution'}}</option>
+                        {{#each ../../resolutions}}
+                            <option value="{{resolutionType}}">{{label}}</option>


Resolution option value mismatch

Medium Severity

Resolution <option> values use resolutionType, while buildRequestedResolution() treats any non-system value as customResolutionEntityId. Custom resolutions whose type is CUSTOM can send the literal string CUSTOM instead of the real entity id.

Additional Locations (1)

assets/js/theme/create-return.js#L115-L123

^{Reviewed by Cursor Bugbot for commit bcea92e. Configure here.}

cursor · 2026-06-30T02:29:09Z

+                    <h6 class="account-orderStatus-label account-orderStatus-label--closed">{{lang 'account.returns.status.closed'}}</h6>
+               {{/if}}
+            </div>
+            <a class="button button--small" href="/account.php?action=view_return&return_id={{id}}">{{lang 'account.returns.list.view_details'}}</a>


Return details link wrong locale

Medium Severity

The “View details” link uses a hardcoded /account.php?action=view_return&return_id=... href instead of a storefront urls helper, so on multi-language sites the link may leave the active locale path and fail or show the wrong context.

^{Reviewed by Cursor Bugbot for commit 281c2c9. Configure here.}

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 7 total unresolved issues (including 6 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 34bc18e. Configure here.}

cursor · 2026-06-30T02:40:09Z

+            } finally {
+                this.isSubmitting = false;
+                if (submitBtn) submitBtn.disabled = false;
+                if (overlay) overlay.style.display = '';


Submit re-enabled without validation

Medium Severity

After a failed or errored createReturn request, the submit handler’s finally block sets return-new-submitBtn to enabled without calling updateSubmitState(), so the button can stay clickable when no line items have quantity, resolution, and reason filled in.

^{Reviewed by Cursor Bugbot for commit 34bc18e. Configure here.}

…2653) * feat(returns): ORDERS-7704 condition for new returns on orders page * feat(returns): ORDERS-7704 condition for new returns on orders page - confirmed

feat(orders): ORDERS-7706 add new return page layout

… page (#2658)

…context (#2665) * feat(returns): ORDERS-7708 new-return page — render items from order context, stepper qty controls, responsive layout, gate behind returns_v2_enabled flag * feat(returns): ORDERS-7708 new-return page - review feedback

feat(orders): ORDERS-7706 add new return page layout

* feat(returns): ORDERS-7764 render create return page with stencil context * feat(returns): ORDERS-7764 render create return page with stencil context * feat(returns): ORDERS-7764 render create return page with stencil context * feat(returns): ORDERS-7764 render create return page with stencil context * feat(returns): ORDERS-7764 fix code review comments * feat(returns): ORDERS-7764 fix code review comments * feat(returns): ORDERS-7764 fix design feedback * feat(returns): ORDERS-7764 fix design feedback

…e/tablet views

…page to returnsV2 create return

)

…enum

…lback

bc-vivekaggarwal requested review from BC-SEven, bc-bryan, denis-bc, jpajar and matt-evangelidis May 27, 2026 00:42

bc-vivekaggarwal requested a review from a team as a code owner May 27, 2026 00:42

denis-bc requested a review from Copilot May 27, 2026 00:50

BC-SEven added the do not merge label May 27, 2026

BC-SEven changed the title ~~Project-7525: Feature branch for the new returns flow~~ Project-7525: [DO NOT MERGE] Feature branch for the new returns flow May 27, 2026

Copilot started reviewing on behalf of denis-bc May 27, 2026 01:00 View session

denis-bc requested review from Copilot and removed request for Copilot May 27, 2026 03:33

Copilot started reviewing on behalf of denis-bc May 27, 2026 03:33 View session

Copilot AI reviewed May 27, 2026

View reviewed changes

cursor Bot reviewed May 28, 2026

View reviewed changes

Comment thread assets/js/app.js Outdated

cursor Bot reviewed Jun 2, 2026

View reviewed changes

Comment thread assets/js/theme/add-return-new.js Outdated

cursor Bot reviewed Jun 9, 2026

View reviewed changes

Comment thread templates/pages/account/add-return.html Outdated

cursor Bot reviewed Jun 17, 2026

View reviewed changes

cursor Bot reviewed Jun 23, 2026

View reviewed changes

Comment thread templates/components/account/returns-list-v2.html Outdated

cursor Bot reviewed Jun 30, 2026

View reviewed changes

jpajar and others added 7 commits July 1, 2026 11:07

feat(orders): ORDERS-7706 add new return page layout

330b8e9

feat(returns): ORDERS-7704 condition for new returns on orders page (#…

ac9bf8a

…2653) * feat(returns): ORDERS-7704 condition for new returns on orders page * feat(returns): ORDERS-7704 condition for new returns on orders page - confirmed

Merge pull request #2649 from bigcommerce/ORDERS-7706

af49f3e

feat(orders): ORDERS-7706 add new return page layout

feat(returns): ORDERS-7705 condition for new returns on order details…

14208d9

… page (#2658)

feat(orders): ORDERS-7734 add template for guest return portal

2428327

feat(orders): ORDERS-7331 add template for create return page

fe09e79

jpajar and others added 25 commits July 1, 2026 11:07

Merge pull request #2649 from bigcommerce/ORDERS-7706

2d3cdbc

feat(orders): ORDERS-7706 add new return page layout

feat(returns): ORDERS-7717 - add new returns list ui

963636a

feat(returns): ORDERS-7717 - use rma number

ab8f7d5

feat(returns): ORDERS-7717 - add CHANGELOG item

bfe4b85

feat(returns): ORDERS-7717 - address copilot review

c855cfe

feat(orders): ORDERS-7718 add return details page layout

b995492

feat(orders): ORDERS-7718 add status mappping from enum

04f5eef

feat(orders): ORDERS-7707 improve create return page design for mobil…

fe8ed93

…e/tablet views

feat(orders): ORDERS-7715 add createReturn mutation and confirmation …

46ddad6

…page to returnsV2 create return

feat(orders): ORDERS-7715 handle double submissions

d9fa074

feat(orders): ORDERS-7859 add error message on failed return creation

9f59f8d

feat(returns): ORDERS-7857 add loading state as return submission (#2689

74042bb

)

feat(returns): ORDERS-7751 - add return details page data

b751950

feat(orders): ORDERS-7751 add placeholder image

8c78e1f

feat(returns): ORDERS-7751 check resolution and requested exist

3bfab15

feat(returns): ORDERS-7751 use handlebars for details templates

156d3c2

feat(returns): ORDERS-7751 update thumbnail image TODO with id

521b10d

feat(returns): ORDERS-7751 remove unused localization keys and markup

381223d

feat(returns): ORDERS-7751 use span tag instead of dt tag

2d58e1e

feat(returns): ORDERS-7751 output localized string instead of status …

b73b93b

…enum

feat(returns): ORDERS-7751 add sr-only label for orderId

095fd05

feat(returns): ORDERS-7751 remove per item status

baca54d

feat(returns): ORDERS-7751 add order_number_label key

ac75952

feat(returns): ORDERS-7751 reference correct object for thumbnail fal…

38101ea

…lback

BC-SEven force-pushed the feature/PROJECT-7525-new-returns-flow branch from 34bc18e to 38101ea Compare July 1, 2026 01:09

		{{> components/common/breadcrumbs breadcrumbs=breadcrumbs}}

		<h1> Guest Return Portal</h1>

Uh oh!

Conversation

bc-vivekaggarwal commented May 27, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Requirements

Tickets / Documentation

Screenshots (if appropriate)

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

denis-bc commented May 28, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot Jun 17, 2026

Choose a reason for hiding this comment

Return policy URL not localized

Uh oh!

Uh oh!

Uh oh!

cursor Bot Jun 23, 2026

Choose a reason for hiding this comment

Additional note omitted from payload

Uh oh!

cursor Bot Jun 23, 2026

Choose a reason for hiding this comment

GraphQL URL ignores storefront base

Uh oh!

cursor Bot Jun 23, 2026

Choose a reason for hiding this comment

Resolution option value mismatch

Uh oh!

Uh oh!

cursor Bot Jun 30, 2026

Choose a reason for hiding this comment

Return details link wrong locale

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jun 30, 2026

Choose a reason for hiding this comment

Submit re-enabled without validation

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

bc-vivekaggarwal commented May 27, 2026 •

edited by cursor Bot

Loading