feat(backorders): BACK-655 render picklist backorder prompt on PDP

[agchan12]

What?

• Use the selected_picklist_options and picklist_products_details from POST /remote/v1/product-attributes/:productId and render a per picklist backorder prompt in addition to the main product stock on the Stencil PDP.

Requirements

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

Tickets / Documentation

Add links to any relevant tickets and documentation.

• BACK-655

Screenshots (if appropriate)

Display backorder prompt when picklist 'Adjust inventory for these products...' is selected

• Main product (103)
  • {on_hand: 10, backorder_limit: 15, backorder_message: 'Backorder message 1'}
  • Picklist_1 product (id: 80) - {on_hand: 0, backorder_limit: unlimited, backorder_message: 'Backorder message 1'}.
    • Adjust inventory for these products when purchased is enabled
  • Picklist_2 product (id: 80) - {on_hand: 0, backorder_limit: unlimited, backorder_message: 'Backorder message 1'}.
    • Adjust inventory for these products when purchased is enabled

BACK-655.mov

Explanation
When a picklist item is selected, the backorder prompt is displayed.

Display backorder prompt when picklist 'Adjust inventory for these products...' is NOT selected

• Main product (103)
  • {on_hand: 10, backorder_limit: 15, backorder_message: 'Backorder message 1'}
  • Picklist_1 product (id: 80) - {on_hand: 0, backorder_limit: unlimited, backorder_message: 'Backorder message 1'}.
    • Adjust inventory for these products when purchased is NOT enabled
  • Picklist_2 product (id: 80) - {on_hand: 0, backorder_limit: unlimited, backorder_message: 'Backorder message 1'}.
    • Adjust inventory for these products when purchased is NOT enabled

BACK-655-adjust.mov

Explanation
When a picklist item is selected, the backorder prompt is NOT displayed.

Display backorder prompt when 'Qty on backorder display' is selected AND picklist 'Adjust inventory for these products...' is and is NOT selected

• Inventory Settings - Qty on backorder display and backorder message is selected
• Main product (103)
  • {on_hand: 10, backorder_limit: 15, backorder_message: 'Backorder message 1'}
  • Picklist_1 product (id: 80) - {on_hand: 0, backorder_limit: unlimited, backorder_message: 'Backorder message 1'}.
    • Adjust inventory for these products when purchased is enabled
  • Picklist_2 product (id: 80) - {on_hand: 0, backorder_limit: unlimited, backorder_message: 'Backorder message 1'}.
    • Adjust inventory for these products when purchased is NOT enabled

BACK-655-qty-backorder.mov

Explanation

We can see that only the qty for backorder for picklist item 1 (Bundle 1) is displayed.

Display backorder prompt when 'Qty on backorder display' is not selected AND picklist 'Adjust inventory for these products...' is and is NOT selected

• Inventory Settings - Qty on backorder display and backorder message is not selected
• Main product (103)
  • {on_hand: 10, backorder_limit: 15, backorder_message: 'Backorder message 1'}
  • Picklist_1 product (id: 80) - {on_hand: 0, backorder_limit: unlimited, backorder_message: 'Backorder message 1'}.
    • Adjust inventory for these products when purchased is enabled
  • Picklist_2 product (id: 80) - {on_hand: 0, backorder_limit: unlimited, backorder_message: 'Backorder message 1'}.
    • Adjust inventory for these products when purchased is NOT enabled

Screen.Recording.2026-05-29.at.11.41.18.am.mov

Explanation
No backorder message is displayed and the qty for backorder for both the main product and the picklist item is not displayed

ping @bc-shawnwang @animesh1987 @bigcommerce/team-trac

---

Note

Medium Risk
Changes PDP inventory/backorder UX and quantity messaging logic; incorrect clamping or flags could misstate backorder qty for bundled picklist products.

Overview
Adds per-picklist backorder messaging on the PDP using selected_picklist_options and picklist_products_details from the product-attributes API. A new PicklistBackorder module renders a list under the stock block (attribute name, backordered qty, optional message), wired into option changes and quantity updates via render / rerender.

Inventory display tweaks: main-product qty-on-backorder now respects showQuantityOnBackorder (replacing the prior flag check), and the backorder availability prompt is shown without wrapping parentheses. Stock copy uses “in stock” next to the level, with SCSS to align stock, main backorder, and picklist lines.

Tests: broad unit coverage for picklist backorder rules (auto-adjust flag, sell limits, AFB clamping, settings toggles).

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

[bc-shawnwang]

code LGTM and the two manual test cases is as expected.

[JessicaHu51]

hey a few edits:

1. in scenario 1, can we use the "picklist name" the merchant entered on the picklist editing page for the PDP backorder display? it's currently using the product name. so in your example it should show "**Bundle 1:** x will be backordered | Backorder message". picklist name should be in bold

2. in both scenarios, can we remove the parent product name? display the parent product's backorder info the same way as a simple product. this avoids repeating a long product name and aligns with how it's displayed in cart and the merchant facing workflow.

The above 2 are design change. Added a mockup below for intended display:

3. In scenario 1, please make sure only quantity on backorder and backorder message shows for picklist items. At 00:36 in the first video i can see the backorder availability prompt showing for Bundle 1 but it should only be the backorder message there

Thanks. let me know if anything isn't clear enough

cc @animesh1987

[bc-shawnwang]

@JessicaHu51 for your comment

"picklist name" the merchant entered on the picklist editing page for the PDP backorder display? it's currently using the product name. so in your example it should show "Bundle 1: x will be backordered | Backorder message"

Just remind this display is not accurate, and might not match the backorder prompts after added to cart. because it doesn't count the cart might already have same items.
e.g

apple has 5 onhand available and 100 backorder available

cart already have 6 x apple (5 on-hand 1 backordered). This is not considered on the PDP page (I think we decided not to calculate it, as luke recorded it somewhere in ADR). At least there is a slack thread on it: https://bigcommerce.slack.com/archives/C081DP3B6MV/p1762732177432859?thread_ts=1762728031.783749&cid=C081DP3B6MV

I raised this because I saw the ticket https://bigcommercecloud.atlassian.net/browse/BACK-627 seems it want to consider current cart status?

[bc-shawnwang]

https://bigcommercecloud.atlassian.net/browse/BACK-627

@JessicaHu51 also if you check the tickets and design screenshot, it did only per product. Since you made a design change, can you aslo change the screenshot on the jira ticket?

[JessicaHu51]

• the vertical spacing between "Qty in stock" and "Qty will be backordered" lines should match the gap between bundle 1 and 2, so the grouping is clearer to read.

• can we also stress test with a 50 character backorder message to make sure it wraps to a second line with the same line gap?

other that these, it looks great! thanks @agchan12

[bc-shawnwang]

Hi @agchan12 I tested on your branch, found something might need to take a look

inventory settings considered?

When I uncheck Quantity on backorder and backorder message, PDP still displayed them, for either main item (not about this PR though) or bundled item

@JessicaHu51 in this case should we not display Quantity on backorder and backorder message?

[agchan12]

Hey @JessicaHu51

Another question about the behaviour of the picklist items (this is similar to the issue Shawn flagged)

Setup:

Main product with two picklist attributes (Bundle 1, Bundle 2)
Both bundles link to the same product (product 80, on_hand: 1, unlimited backorder)
Shopper selects both bundles
The problem: Product 80 only has 1 unit in stock, but both bundles need it. When the shopper checks out at qty=1, 1 unit will be backordered. At qty=3, 5 units will be backordered (3 per bundle × 2 bundles = 6 total demand, minus 1 on-hand = 5).

There are two ways to display this, each with a trade-off:

Option A: Independent (each bundle shows its own view of the product's stock) (No consideration of cart content):

Bundle 1: (no backorder shown)
Bundle 2: (no backorder shown)
Each bundle sees 1 on-hand vs 1 demanded. This is simple to implement and doesn't overcomplicate things. This is similar to the approximation discussion that Shawn raised in BACK-627.

Option B: Shared pool (No consideration of cart content)

Bundle 1: (no backorder)
Bundle 2: 1 will be backordered

This is partially accurate and doesn't account for what is already in the cart (which could also be misleading) is harder to calculate.

Option A is simpler and consistent with how main product backorder already works (doesn't account for other demand sources). Option B warns the shopper but introduces asymmetry and partial precision. Happy to implement either.

[cursor]

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

^{❌ 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 33501cf. Configure here.}

[agchan12]

@bc-shawnwang In regards to #2662 (comment)

I have made some changes to the PR

I have made some changes to the main product and picklist. The picklist backorder display now respects the store level inventory display settings directly:

• Quantity on backorder checkbox gates whether "X will be backordered" renders. When unchecked, the entire qty line is suppressed for both picklist items and the main product.
• Backorder message checkbox gates whether the per-product backorder message suffix renders. When unchecked, the backorder message part is omitted.

[agchan12]

@JessicaHu51 In regards to #2662 (comment)

I believe the spacing and wrap around spacing are all vertically the same now

[bc-shawnwang]

FYI, for bundled item set to NOT "adjust inventory", what we do is to still check if it is within ATS (onhand without backorder feature, plus backorder available if backorder feature enabled), but not calculate and display xxx is backordered.

[bc-yevhenii-buliuk]

good job!