Backorder Issue — ACCS-216 (PDP Troubleshooting)

astro.sidebar.mjs

@@ -349,6 +349,7 @@ export function generateSidebar() {
                 { label: 'Slots', link: '/dropins/product-details/slots/' },
                 { label: 'Events', link: '/dropins/product-details/events/' },
                 { label: 'Dictionary', link: '/dropins/product-details/dictionary/' },
+                { label: 'Troubleshooting', link: '/dropins/product-details/troubleshooting/' },
               ],
             },
             {

src/content/docs/boilerplate/getting-started.mdx

@@ -82,7 +82,7 @@ The boilerplate is organized into these main directories:
 
 ## Understanding the flow
 
-To understand how documents transform into rendered commerce experiences at runtime, see the [Runtime flow](/get-started/architecture/#runtime-flow) section in the architecture guide. This foundational knowledge helps you know where to customize and integrate with the boilerplate.
+To understand how documents transform into rendered commerce experiences at runtime, see the [architecture guide](/get-started/architecture/). This foundational knowledge helps you know where to customize and integrate with the boilerplate.
 
 ## Customizing your storefront
 

src/content/docs/dropins/product-details/troubleshooting.mdx

@@ -0,0 +1,85 @@
+---
+title: Product Details Troubleshooting
+description: Troubleshoot backorder status issues on the product details page.
+sidebar:
+  label: Troubleshooting
+  order: 9
+---
+
+import { Aside, Steps } from '@astrojs/starlight/components';
+import Link from '@components/Link.astro';
+
+Troubleshoot backorder status issues on the product details page.
+
+## Backorder status toggle switches off unexpectedly
+
+<Aside type="note" title="About this issue">
+This troubleshooting entry is based on a customer-reported support issue. The "backorder toggle" refers to a Commerce Admin interface element for configuring product backorder settings (accessible via **Catalog** > **Products** > edit product > **Advanced Inventory**). The Commerce Admin interface is not part of the storefront codebase, but the data synchronization mechanism (SaaS Data Export) that syncs inventory changes from Commerce to Catalog Service is documented and verifiable.
+</Aside>
+
+**Symptom:** The backorder toggle switches on when an ERP notifies Adobe Commerce that a product is backordered, but then switches off after a period of time, even though the ERP has not adjusted the quantity available.
+
+**Impact:** Customers see products as deliverable when they're actually on backorder, leading to order fulfillment issues.
+
+**Expected behavior:**
+
+The backorder toggle is a **configuration setting** that defines how products behave when stock quantity is 0 (whether to allow customers to purchase out-of-stock items). The backorder setting is a static configuration and is **not intended to change automatically** based on stock quantity changes. 
+
+If you need the backorder toggle to change dynamically based on stock levels, implement a custom runtime action that:
+
+- Subscribes to inventory change events.
+- Calls Adobe Commerce APIs to update the backorder flag when quantity reaches 0.
+- Operates at the integration level (for example, a custom integration), not in core storefront code.
+
+For more information about configuring backorders, see the <Link href="https://experienceleague.adobe.com/en/docs/commerce-admin/inventory/configuration/backorders#configure-backorders-for-a-product" text="Commerce Admin backorder configuration documentation" />.
+
+**Verify the issue:**
+
+<Steps>
+
+1. **Check the browser console for product data updates.**
+
+   ```javascript
+   // Listen to product data events
+   import { events } from '@dropins/tools/event-bus.js';
+
+   events.on('pdp/data', (payload) => {
+     if (payload) {
+       console.log('Product data:', payload);
+       console.log('In stock:', payload.inStock);
+       console.log('Add to cart allowed:', payload.addToCartAllowed);
+       console.log('SKU:', payload.sku);
+     }
+   });
+   ```
+
+1. **Check the Commerce Admin backorder setting.**
+
+   - Navigate to **Catalog** > **Products** and open the product in edit mode.
+   - Click **Advanced Inventory** to view the backorder settings.
+   - Verify the backorder toggle is set as expected.
+
+</Steps>
+
+**What to check:**
+
+- **Expected behavior**: Verify that the backorder toggle is set as a static configuration and not changing automatically based on stock quantity. The backorder setting should remain consistent regardless of stock level changes.
+- **Custom runtime actions**: Check if any custom runtime actions or integrations subscribe to inventory change events and automatically update the backorder flag. If dynamic backorder behavior is needed, implement it at the integration level (for example, a custom integration), not in core storefront code.
+- **ERP integration**: Verify that your ERP system correctly sends backorder status to Adobe Commerce via API. Check your ERP integration logs and Adobe Commerce backend logs for API call success or failure. The integration typically uses Adobe Commerce REST or GraphQL APIs, but specific implementation details vary by customer. ERP systems should not automatically toggle the backorder setting based on stock levels.
+- **API response**: Confirm the Catalog Service GraphQL API returns the correct `inStock` and `addToCartAllowed` values.
+- **Data refresh**: Check if product data is being refreshed from a different source that overwrites the backorder status.
+- **Event handlers**: Review any custom event handlers that might update product availability or backorder settings.
+
+**Workaround:**
+
+Monitor product availability in real-time and manually verify backorder status in your Commerce Admin before fulfilling orders.
+
+**Next steps:**
+
+If the issue persists, collect the following information for support:
+
+- Product SKU(s) experiencing the issue.
+- Timestamp when backorder status was set.
+- Timestamp when toggle switched back to off.
+- API response from Catalog Service at both timestamps.
+- Browser console logs showing product data updates.